Skip to content

5. Clases de .NET de uso frecuente

Aquí presentamos algunas clases de uso frecuente de la plataforma .NET: cadenas, arreglos, colecciones, archivos y expresiones regulares. También trataremos LINQ (Language Integrated Query), que el curso de 2008 omitía aunque ya estaba disponible desde C# 3: hoy es la forma más común de manipular colecciones en C#. Antes, veremos cómo encontrar información sobre las miles de clases disponibles. Esta guía es indispensable para cualquier desarrollador de C#, incluso con experiencia.

Los ejemplos de este capítulo, con excepción de la aplicación de ejemplo del final, son aplicaciones de un solo archivo ejecutadas con [dotnet run file.cs]. Se encuentran en la carpeta [05-classes-dotnet] del código del curso y se ejecutan con la configuración regional francesa (fr-FR), salvo los ejemplos de LINQ y de expresiones regulares, que se ejecutan con la configuración regional del inglés estadounidense (en-US).

5.1. Cómo encontrar ayuda sobre las clases de .NET

El curso de 2008 ofrecía una descripción detallada, con capturas de pantalla, de la ayuda de MSDN instalada con Visual Studio 2008. Esta ayuda local ya no está disponible: la documentación de .NET ahora está en línea, es gratuita y se actualiza con cada nueva versión.

5.1.1. Documentación en línea

El punto de partida es el sitio web de Microsoft learn.microsoft.com. Allí encontrará:

  • la documentación del lenguaje C#: https://learn.microsoft.com/en-us/dotnet/csharp/. Incluye una visión general del lenguaje, tutoriales, la referencia del lenguaje (palabras clave, operadores, instrucciones) y una sección “Novedades” que describe cada versión de C#;
  • la referencia de la API de .NET: https://learn.microsoft.com/en-us/dotnet/api/. Describe, espacio de nombres por espacio de nombres, todas las clases de .NET: sus constructores, propiedades y métodos, con ejemplos;
  • el explorador de API, en la misma página: un cuadro de búsqueda donde se puede escribir el nombre de una clase o método ([StringBuilder], [Regex.Match]…). Una lista desplegable permite seleccionar la versión de .NET (aquí, .NET 10).

La página de una clase, como System.String, muestra:

  • el espacio de nombres de la clase y el ensamblado que la contiene;
  • su declaración, su clase padre y las interfaces que implementa;
  • una lista de sus constructores, propiedades y métodos, cada uno con un enlace a una página detallada que muestra sus diversas sobrecargas, parámetros, valores de retorno, posibles excepciones y, a menudo, un ejemplo;
  • notas sobre su uso.

Las páginas están disponibles en francés (traducción automática) y en inglés (texto original, que a veces es más preciso). Se puede cambiar de uno a otro reemplazando [en-us] por [fr-fr] en la URL. Una búsqueda en un motor de búsqueda con el nombre completo de la clase (“System.Text.StringBuilder”) suele llevar directamente a la página correcta.

5.1.2. Ayuda del editor

El editor de código (Visual Studio, Visual Studio Code con la extensión C# Dev Kit, Rider) ofrece ayuda inmediata sin salir del código:

  • el autocompletado (IntelliSense): después de escribir [aString.], el editor sugiere una lista de las propiedades y métodos del objeto, junto con un resumen de cada uno;
  • Información sobre herramientas: al colocar el mouse sobre el nombre de una clase, método o variable, se muestra su declaración y un resumen de su documentación;
  • Ayuda de parámetros: al escribir el paréntesis de apertura de una llamada, el editor muestra las diferentes sobrecargas del método y la función de cada parámetro;
  • Ir a la definición (tecla F12): muestra la declaración de la clase o del método. Para una clase de .NET, el editor muestra las declaraciones públicas reconstruidas a partir del ensamblado, junto con sus comentarios de documentación;
  • En Visual Studio, al pulsar la tecla F1 sobre el nombre de una clase o método se abre la página correspondiente de la documentación en línea.

Estos comentarios de documentación, que se ven al colocar el mouse sobre un elemento, son los que se usan para generar la referencia en línea. Se pueden escribir comentarios similares en el código propio mediante la sintaxis [/// <summary> ... </summary>] colocada encima de una clase o método: el editor los mostrará de la misma manera.

5.2. Cadenas

5.2.1. La clase System.String

El tipo [string] de C# es un alias de la clase [System.String]. Tiene numerosas propiedades y métodos. Estos son algunos de ellos:

Miembro
función
[public int Length { get; }]
número de caracteres de la cadena
[public char this[int index] { get; }]
Carácter n.º [index]: [aString[i]]
[public bool StartsWith(string value)]
devuelve [true] si la cadena comienza con [value]
[public bool EndsWith(string value)]
devuelve [true] si la cadena termina con [value]
[public bool Contains(string value)]
devuelve [true] si la cadena contiene [value]
[public bool Equals(string? value)]
devuelve [true] si la cadena es igual a [value]; equivale a [aString == value]
[public int IndexOf(string value)]
la primera aparición de [value] en la cadena, o -1. Otra sobrecarga inicia la búsqueda en la posición [startIndex]
[public int IndexOf(char value)]
lo mismo para el carácter [value]
[public int LastIndexOf(char value)]
igual que [IndexOf] pero devuelve la última posición en lugar de la primera
[public string Insert(int startIndex, string value)]
inserta la cadena [value] en la cadena en la posición [startIndex]
[public static string Join(string separator, params string[] value)]
método de clase: concatena los elementos de [value], separándolos con [separator]
[public string Replace(char oldChar, char newChar)]
devuelve una copia de la cadena en la que el carácter [oldChar] se ha reemplazado por [newChar]; un método sobrecargado reemplaza una cadena por otra
[public string[] Split(params char[] separator)]
la cadena se trata como una secuencia de campos separados por los caracteres de [separator]; el resultado es un arreglo con estos campos
[public string Substring(int startIndex, int length)]
una subcadena de [length] caracteres que comienza en la posición [startIndex]
[public string ToLower()], [public string ToUpper()]
convierte la cadena a minúsculas, mayúsculas
[public string Trim()]
elimina los espacios iniciales y finales de la cadena ([TrimStart], [TrimEnd]: solo en uno de los extremos)

Es importante observar que una cadena del tipo [string] es inmutable; no se puede modificar después de crearla. Cuando un método devuelve una cadena, esta es distinta de la cadena a la que se aplicó el método. Así, [s1.Trim()] devuelve la cadena [s2], y [s1] y [s2] son dos cadenas diferentes: [s1] no ha cambiado.

Una cadena [c] puede considerarse un arreglo de caracteres de solo lectura:

  • [c[i]] es el i-ésimo carácter de [c] (el primer carácter es el número 0);
  • [c.Length] es el número de caracteres de [c].

El programa [strings-01.cs] es el siguiente:

// algunos métodos de la clase 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 "));
// división de la cadena en palabras (separador: espacios)
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() + "]");
// la cadena original no se ha modificado
Display("aString=" + aString);

// un método local de visualización
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

Comentarios:

  • línea 5: el carácter n.º 10, es decir, el undécimo carácter de la cadena;
  • líneas 7 y 9: una búsqueda fallida devuelve -1;
  • línea 10: los 7 caracteres a partir de la posición 4;
  • línea 14: una inserción en la posición 9, antes de la palabra “flies”;
  • línea 16: [Split] sin parámetros divide la cadena en los caracteres de espacio en blanco (espacio, tabulación, salto de línea, etc.). El curso de 2008 usaba [Split(null)], que equivale a lo mismo;
  • línea 21: el método estático [Join] hace lo contrario de [Split];
  • Línea 23: todos los métodos anteriores devolvían cadenas nuevas: [aString] permaneció sin cambios (línea 21 de los resultados);
  • Líneas 27–29: una función local, como en el capítulo 3.

5.2.2. Los métodos Split y Join

El programa [strings-02.cs] profundiza en la división de una cadena en campos:

// Split y Join
string line = "one:two::three:";
// división con el separador ':'
string[] fields = line.Split(':');
for (int i = 0; i < fields.Length; i++)
{
    Console.WriteLine($"fields[{i}]=[{fields[i]}]");
}
// la operación inversa
Console.WriteLine($"join=[{string.Join(":", fields)}]");

// las opciones de Split: eliminación de los campos vacíos
fields = line.Split(':', StringSplitOptions.RemoveEmptyEntries);
Console.WriteLine($"RemoveEmptyEntries : {fields.Length} fields [{string.Join("|", fields)}]");

// varios separadores y eliminación de los espacios alrededor de los campos
string person = " dupont , jean ;  45 ";
fields = person.Split([',', ';'], StringSplitOptions.TrimEntries);
Console.WriteLine($"TrimEntries : {fields.Length} fields [{string.Join("|", fields)}]");

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

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

// Join acepta cualquier colección, no solo cadenas
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

Comentarios:

  • Línea 4: los campos están separados por el carácter [:]. Dos caracteres [:] consecutivos, o un solo [:] al final de la cadena, delimitan un campo vacío: esto da como resultado 5 campos, 2 de ellos vacíos (líneas 4 y 6 de los resultados). [Join] reconstruye la cadena original;
  • el método [Split] tiene numerosas sobrecargas. La versión de 2008, [Split(char[] separator)], ahora se escribe [Split(params char[] separator)]: la palabra clave [params] permite pasar los separadores uno por uno, [Split(':')] o [Split(',', ';')], sin crear un arreglo;
  • Línea 13: la enumeración [StringSplitOptions] modifica el desglose de los campos. [RemoveEmptyEntries] elimina los campos vacíos;
  • línea 18: [TrimEntries] (.NET 5) elimina los espacios alrededor de cada campo. Aquí los separadores se pasan como una expresión de colección [',', ';'];
  • línea 23: las dos opciones se combinan con el operador [|]. Los espacios se eliminan antes de la verificación de campos vacíos: se elimina el campo formado por dos espacios entre dos comas;
  • línea 28: el separador puede ser una cadena formada por varios caracteres;
  • línea 33: [Join] acepta una colección de elementos de cualquier tipo; cada elemento se convierte en cadena mediante su método [ToString].

5.2.3. Búsqueda y comparación de cadenas

La comparación de cadenas es más sutil de lo que parece: ¿deben distinguirse las mayúsculas de las minúsculas? ¿Cómo se debe ordenar “éclair” respecto de “essay”? El programa [strings-03.cs] presenta los métodos de búsqueda y comparación:

// búsqueda y comparación de cadenas
string title = "Learning the C# language with .NET";

// Contains, StartsWith, EndsWith: comparación exacta por defecto
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')}");

// el modo de comparación se especifica con la enumeración StringComparison
Console.WriteLine($"Contains(\"LANGUAGE\", OrdinalIgnoreCase) : {title.Contains("LANGUAGE", StringComparison.OrdinalIgnoreCase)}");
Console.WriteLine($"StartsWith(\"learning\", OrdinalIgnoreCase) : {title.StartsWith("learning", StringComparison.OrdinalIgnoreCase)}");

// igualdad: el operador == compara el contenido de las cadenas
string answer = "YES";
Console.WriteLine($"answer == \"yes\" : {answer == "yes"}");
Console.WriteLine($"string.Equals(answer, \"yes\", OrdinalIgnoreCase) : {string.Equals(answer, "yes", StringComparison.OrdinalIgnoreCase)}");

// orden alfabético: comparación según la cultura o según los códigos de los 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)}");

// cadenas vacías o en blanco
string? empty = null;
string blank = "   ";
Console.WriteLine($"IsNullOrEmpty(null) : {string.IsNullOrEmpty(empty)}");
Console.WriteLine($"IsNullOrEmpty(\"   \") : {string.IsNullOrEmpty(blank)}");
Console.WriteLine($"IsNullOrWhiteSpace(\"   \") : {string.IsNullOrWhiteSpace(blank)}");

// relleno (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.....] [--------]

Comentarios:

  • líneas 5–8: [Contains], [StartsWith], y [EndsWith] realizan por defecto una comparación exacta, carácter por carácter: “LANGUAGE” no se encuentra;
  • Líneas 11–12: un parámetro del tipo [StringComparison] especifica el modo de comparación. Los valores más útiles son:
    • [Ordinal]: comparación de códigos de caracteres;
    • [OrdinalIgnoreCase]: igual que el anterior, ignorando mayúsculas y minúsculas;
    • [CurrentCulture], [CurrentCultureIgnoreCase]: comparación según las reglas del idioma de la máquina;
    • [InvariantCulture]: comparación basada en reglas independientes de la máquina;
  • línea 16: el operador [] compara el contenido de las cadenas, igual que el método [Equals]. Esta es una diferencia importante con Java, donde [] compara referencias;
  • línea 17: la forma estática de [Equals] también acepta un [StringComparison]. Esta es la manera correcta de evaluar una respuesta “yes” ingresada por teclado en mayúsculas o minúsculas;
  • Líneas 21–22: [string.Compare] devuelve un entero negativo, cero o positivo según que la primera cadena vaya antes, sea igual o vaya después de la segunda. En francés, “éclair” va antes de “essay” (la letra “é” se clasifica junto con la “e”, línea 10 de los resultados). En la comparación ordinal, “éclair” va después de “essay” porque el código del primer carácter, “é” (233), es mayor que el del carácter “e” (101): la comparación ordinal devuelve aquí la diferencia entre los dos códigos, 132. Usaremos el orden cultural para ordenar palabras destinadas a un usuario y el orden ordinal para comparar identificadores técnicos (nombres de archivo, claves, etc.);
  • líneas 27–29: dos métodos estáticos para evaluar una cadena ausente ([null]), vacía o que contiene solo espacios;
  • Línea 32: [PadLeft] y [PadRight] rellenan una cadena hasta una longitud dada; el constructor [new string('-', 8)] repite un carácter.

5.2.4. Interpolación y formatos

La interpolación de cadenas [$"..."] (C# 6) se usa desde el comienzo de este curso. Al igual que el método [string.Format], acepta un ancho y un formato para cada expresión: [{expression,width:format}]. El programa [strings-04.cs] ofrece ejemplos de ello, así como de las cadenas sin formato (raw) de C# 11:

// interpolación, formatos y cadenas sin procesar
string name = "dupont";
int age = 45;
decimal salary = 2345.678m;
double rate = 0.0525;
DateTime date = new(2026, 10, 3, 14, 5, 9);

// interpolación simple
Console.WriteLine($"{name} is {age} years old");
// {expresión,ancho:formato}: un ancho > 0 alinea a la derecha, < 0 alinea a la izquierda
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}]");
// cualquier expresión, aquí una expresión condicional entre paréntesis
Console.WriteLine($"{name} is {(age >= 18 ? "an adult" : "a minor")}");

// el método string.Format y la notación {n} de las versiones anteriores de C#
Console.WriteLine(string.Format("{0} is {1} years old and earns {2:F2} euros", name, age, salary));

// una tabla alineada
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} €");
}

// cadena textual (verbatim): \ no es un carácter de escape
string path = @"C:\data\course\infos.txt";
Console.WriteLine(path);

// cadena sin procesar (raw string) (C# 11): delimitada por al menos tres comillas dobles, en varias líneas
string json = """
    {
      "name": "dupont",
      "path": "C:\data"
    }
    """;
Console.WriteLine(json);
// cadena sin procesar interpolada: con $$, las llaves simples siguen siendo literales
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 }

Comentarios:

  • línea 11: un ancho positivo alinea el valor a la derecha dentro de un campo de 10 caracteres; un ancho negativo lo alinea a la izquierda;
  • Líneas 12–14: los formatos más comunes:
formato
significado
ejemplo (fr-FR)
[F2]
número de punto fijo, 2 decimales
2345,68
[N2]
igual que el anterior, con separador de miles
2 345,68
[C]
importe monetario según la cultura actual
2 345,68 €
[P2]
porcentaje (el valor se multiplica por 100)
5,25 %
[D5]
entero de 5 dígitos o más, rellenado con ceros
00045
[X]
entero hexadecimal
2D
[dd/MM/yyyy], [HH:mm:ss]
fecha y hora (MM: mes, mm: minutos)
03/10/2026, 14:05:09
[dddd d MMMM yyyy]
día y mes escritos con letras
samedi 3 octobre 2026
  • Los números y las fechas se formatean según la configuración regional actual, en este caso fr-FR: coma decimal, espacio como separador de miles, nombres de días y meses en francés;
  • línea 16: una expresión condicional ubicada dentro de una interpolación debe ir entre paréntesis, porque el carácter [:] introduciría allí un formato;
  • línea 19: la notación [{0}], [{1}]… para [string.Format] es la que se usaba en el curso de 2008 (y en [Console.WriteLine], que acepta los mismos parámetros). Todavía se encuentra con frecuencia; la interpolación es más legible;
  • líneas 24–26: los anchos permiten mostrar los datos en columnas;
  • línea 30: una cadena textual [@"..."] no trata [\] como carácter de escape. Esto es útil para rutas de Windows y expresiones regulares;
  • líneas 34–39: una cadena sin formato (C# 11) se delimita con al menos tres comillas dobles. Puede abarcar varias líneas y contener comillas sin escapar y [\]. La sangría de la comilla de cierre se elimina de cada línea: el texto JSON se muestra sin los 4 espacios del margen del código;
  • Línea 42: una cadena sin formato puede interpolarse. Con [$$], una expresión interpolada se escribe entre llaves dobles [{{name}}], y las llaves simples —habituales en un texto como JSON— siguen siendo caracteres normales.

5.2.5. La clase System.Text.StringBuilder

Mencionamos que los métodos de la clase [String] que operan sobre una cadena [s1] devuelven otra cadena [s2]. La clase [System.Text.StringBuilder] permite modificar una cadena sin crear una nueva en cada operación. Esto mejora el rendimiento al construir una cadena mediante muchas adiciones sucesivas, ya que evita la proliferación de cadenas de vida muy corta.

La clase admite varios constructores:

constructor
función
[StringBuilder()]
constructor predeterminado
[StringBuilder(string value)]
Construye e inicializa con [value]
[StringBuilder(string value, int capacity)]
Construye e inicializa con [value], con una capacidad inicial de [capacity] caracteres

Un objeto [StringBuilder] almacena sus caracteres en una zona de memoria cuyo tamaño —su capacidad— se ajusta automáticamente a medida que el texto crece. Por defecto, la capacidad inicial es de 16 caracteres. El tercer constructor permite especificarla. El programa [strings-05.cs] ilustra este concepto de capacidad:

using System.Text;

// tamaño y capacidad de un 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}");
}
// un StringBuilder con capacidad inicial de 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

Comentarios:

  • línea 4: creación de un objeto [StringBuilder] con una capacidad inicial de 16;
  • línea 5: [Length] es el número actual de caracteres; [Capacity] es el número de caracteres que el objeto puede contener antes de ampliar su zona de memoria;
  • línea 8: [Append] agrega una cadena al final del texto;
  • línea 12: creación de un objeto [StringBuilder] con una capacidad inicial de 10.

Los resultados muestran que la capacidad se duplica cuando es insuficiente: 16, 32, 64 (líneas 6 y 10 de los resultados), y 10, 20, 40, 80 para el segundo objeto. Son los mismos resultados que en 2008. Si el tamaño aproximado del texto se conoce de antemano, fijarlo en el momento de la construcción evita ampliaciones sucesivas.

Estos son algunos de los métodos de la clase:

método
función
[StringBuilder Append(string value)]
Agrega [value] al final del texto. Sobrecargado para aceptar los tipos [int], [double], [decimal], [char]… y una cadena interpolada
[StringBuilder AppendLine()]
agrega un salto de línea (una sobrecarga agrega una cadena seguida de un salto de línea)
[StringBuilder AppendJoin(string separator, params string[] values)]
agrega los elementos de [values] separados por [separator]
[StringBuilder Insert(int index, string value)]
inserta [value] en la posición [index]; sobrecargado como [Append]
[StringBuilder Remove(int index, int length)]
elimina [length] caracteres a partir de la posición [index]
[StringBuilder Replace(string oldValue, string newValue)]
reemplaza [oldValue] por [newValue]; una sobrecarga reemplaza un carácter
[string ToString()]
convierte el texto en una cadena [string]

El programa [strings-06.cs] los utiliza:

using System.Text;

// los métodos de StringBuilder devuelven el propio objeto StringBuilder: se pueden encadenar
var str3 = new StringBuilder("test");
Console.WriteLine(str3.Append("abCD").Insert(2, "xyZT").Remove(0, 2).Replace("xy", "XY"));

// construcción de una cadena pieza por pieza
var lines = new StringBuilder();
for (int i = 1; i <= 3; i++)
{
    lines.Append("line ").Append(i).AppendLine();
}
// AppendJoin: el equivalente de string.Join
lines.AppendJoin(", ", "a", "b", "c").AppendLine();
// Append también acepta una cadena interpolada
int total = 42;
lines.Append($"total={total,6:F1}");
// la cadena 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

Comentarios:

  • Línea 5: los métodos de modificación devuelven el propio objeto [StringBuilder], lo que permite encadenarlos. Sigamos los pasos: “test” pasa a “testabCD” ([Append]), luego a “texyZTstabCD” ([Insert] en la posición 2), luego a “xyZTstabCD” ([Remove] de los 2 primeros caracteres) y, finalmente, a “XYZTstabCD” ([Replace]). [Console.WriteLine] muestra el objeto llamando a su método [ToString];
  • líneas 9–11: construcción de un texto de varias líneas mediante adiciones sucesivas: este es el uso típico de [StringBuilder];
  • Línea 17: [Append] acepta una cadena interpolada, incluidos el ancho y el formato;
  • Línea 19: el texto final se obtiene como una cadena [string].

Para unas pocas concatenaciones, el operador [+] o la interpolación bastan: el compilador las optimiza. [StringBuilder] es necesario cuando el número de adiciones es grande o desconocido, típicamente en un bucle.

5.2.6. Vistas sobre una cadena: Span<char>

.NET Core 2.1 (2018) introdujo los tipos [Span<T>] y [ReadOnlySpan<T>]. Un objeto [ReadOnlySpan<char>] es una vista de una secuencia de caracteres existente, como una porción de una cadena: no contiene una copia de los caracteres, solo una forma de acceder a ellos. Por lo tanto, extraer una porción de una cadena mediante una vista no crea una nueva cadena. El programa [strings-07.cs] compara las dos formas de analizar una línea con el formato “apellido:nombre:edad”:

// ReadOnlySpan<char>: una "vista" sobre una parte de una cadena, sin copia
string line = "dupont:jean:45";

// con Substring: cada campo es una nueva cadena asignada en memoria
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}");

// con una vista: no se crea ninguna cadena intermedia
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 hasta el final
// int.Parse acepta una vista
age = int.Parse(ageView);
Console.WriteLine($"Span : last name={lastNameView}, age={age}, length of the view={lastNameView.Length}");
// una vista se puede comparar con una cadena sin copiarla
Console.WriteLine($"the last name starts with \"du\": {lastNameView.StartsWith("du")}");
// solo se crea una cadena si realmente es necesario
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

Comentarios:

  • líneas 7–8: cada llamada a [Substring] crea una nueva cadena en memoria, incluso si, como en el caso de la edad, solo se usa un instante;
  • línea 12: [AsSpan] devuelve una vista de la cadena completa;
  • Líneas 13–14: los rangos [start..end] (C# 8), presentados en el capítulo 3 para los arreglos, se aplican a las vistas: se obtienen dos nuevas vistas, sin copia;
  • línea 16: muchos métodos de .NET aceptan una vista en lugar de una cadena ([Parse], [TryParse], [StartsWith], [Contains], [Equals]…);
  • Línea 21: solo se crea una cadena a partir de una vista si realmente es necesario.

Las vistas son una herramienta de optimización muy utilizada dentro del propio .NET: esta es una de las razones por las que las versiones recientes son notablemente más rápidas que .NET Framework 2008. Una vista solo puede existir en la pila de ejecución: no puede, por ejemplo, ser un campo de una clase. Para un programa ordinario, [string] y [Substring] son perfectamente adecuados: las vistas solo deben usarse en código identificado como crítico para el rendimiento. No profundizaremos más.

5.3. Arreglos

5.3.1. La clase Array

Los arreglos derivan de la clase [System.Array]. Esta clase ofrece diversos métodos para ordenar un arreglo, buscar un elemento en un arreglo, redimensionarlo, etc. Presentaremos algunas de sus propiedades y métodos. Casi todos están sobrecargados, es decir, existen en distintas variantes. Todo arreglo los hereda.

Propiedades:

propiedad
función
[public int Length { get; }]
número total de elementos del arreglo, sea cual sea el número de dimensiones
[public int Rank { get; }]
número de dimensiones del arreglo

Métodos:

Método
función
[public static int BinarySearch<T>(T[] array, T value)]
Devuelve la posición de [value] en [array], que debe estar ordenado; un número negativo si [value] no está
[public static void Clear(Array array, int index, int length)]
asigna a los [length] elementos de [array] a partir del índice [index] sus valores predeterminados: 0 para los números, [false] para los booleanos, [null] para las referencias
[public static void Copy(Array source, Array destination, int length)]
copia los primeros [length] elementos de [source] a [destination]
[public static void Fill<T>(T[] array, T value)]
asigna [value] a todos los elementos de [array]
[public int GetLength(int dimension)]
número de elementos de la dimensión n.º [dimension] del arreglo
[public static int IndexOf<T>(T[] array, T value)]
devuelve la posición de [value] en [array], o -1 si [value] no se encuentra; [LastIndexOf] devuelve la última posición
[public static void Resize<T>(ref T[]? array, int newSize)]
redimensiona [array] a [newSize] elementos; los elementos ya presentes se conservan
[public static void Reverse(Array array)]
invierte el orden de los elementos de [array]
[public static void Sort<T>(T[] array)]
ordena [array] según el orden natural de sus elementos; un método sobrecargado recibe un objeto [IComparer<T>] que define el orden (capítulo 4)

El programa [arrays-01.cs] ilustra el uso de ciertos métodos de la clase [Array]:

// la clase Array: cambio de tamaño, ordenamiento, búsqueda

// lectura de los elementos de un arreglo escrito en el teclado
double[] elements = Input();
// visualización del arreglo sin ordenar
Display("Unsorted array", elements);
// búsqueda lineal en el arreglo sin ordenar
Search(elements, SearchType.Linear);
// ordenamiento del arreglo
Array.Sort(elements);
// visualización del arreglo ordenado
Display("Sorted array", elements);
// búsqueda binaria en el arreglo ordenado
Search(elements, SearchType.Binary);

// ingreso de los valores del arreglo: devuelve el arreglo creado
static double[] Input()
{
    // al inicio, el arreglo está vacío
    double[] elements = [];
    // bucle de ingreso de los elementos del arreglo
    while (true)
    {
        Console.Write($"Element (real) {elements.Length} of the array (nothing to finish): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // fin del ingreso si la cadena está vacía
        if (answer == "")
        {
            break;
        }
        // verificación del ingreso
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Incorrect input, try again");
            continue;
        }
        // un elemento más: agrandamos el arreglo en una celda
        Array.Resize(ref elements, elements.Length + 1);
        // y almacenamos en ella el nuevo elemento
        elements[^1] = element;
    }
    return elements;
}

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

// búsqueda en el arreglo de elementos escritos en el teclado
static void Search(double[] elements, SearchType type)
{
    while (true)
    {
        Console.Write("Element searched for (nothing to stop): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // ¿terminó?
        if (answer == "")
        {
            break;
        }
        // verificación
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Error, try again...");
            continue;
        }
        // buscamos el elemento en el arreglo
        int i = type == SearchType.Binary
            ? Array.BinarySearch(elements, element)    // arreglo ordenado
            : Array.IndexOf(elements, element);        // arreglo cualquiera
        // visualización de la respuesta
        Console.WriteLine(i >= 0 ? $"Found at position {i}" : $"Not in the array ({i})");
    }
}

// tipo de búsqueda
enum SearchType { Linear, Binary }

Comentarios:

  • Líneas 17–42: el método [Input] ingresa por teclado los elementos de un arreglo. Como el número de elementos no se conoce de antemano, el programa parte de un arreglo vacío (línea 20) y lo amplía en un elemento por cada nueva entrada (línea 38). [Resize] en realidad crea un nuevo arreglo, copia en él los elementos del anterior y almacena su referencia en la variable pasada por [ref]. Un algoritmo más eficiente reservaría espacio en grupos de N elementos. Un arreglo no está diseñado para redimensionarse: este caso se maneja mejor con una lista [List<T>], como veremos enseguida;
  • línea 40: [^1] designa el último elemento del arreglo (indexado desde el final, C# 8);
  • En el curso de 2008, [Input] era un método con un parámetro [out]; la versión moderna devuelve el arreglo creado, lo cual es más natural;
  • Líneas 56–78: el método [Search] busca en el arreglo los elementos ingresados por teclado. Para un arreglo sin ordenar, se realiza una búsqueda lineal con [IndexOf] (línea 76), que examina los elementos uno por uno. Para un arreglo ordenado, se realiza una búsqueda binaria con [BinarySearch] (línea 75), que reduce a la mitad el rango de búsqueda en cada paso: encuentra un elemento entre un millón en unas veinte comparaciones;
  • línea 10: se ordena el arreglo. Aquí se usa una variante de [Sort] que tiene un solo parámetro: el arreglo por ordenar. La relación de orden utilizada para comparar los elementos del arreglo es entonces la implícita de esos elementos: en este caso, el orden natural de los números;
  • líneas 46–51: un método genérico que muestra un arreglo de elementos de cualquier 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): 

Cuando el elemento buscado está ausente, [IndexOf] devuelve -1 y [BinarySearch] devuelve un número negativo (línea 27): es el complemento a uno ([~i]) de la posición en la que debería insertarse el elemento para mantener el arreglo ordenado. Aquí, [~(-3)] es igual a 2: el número 0 debería insertarse en la posición 2, entre -1.5 y 3.6. Nota: [BinarySearch] sobre un arreglo sin ordenar devuelve un resultado sin sentido.

5.3.2. Otros métodos de la clase Array

El programa [arrays-02.cs] muestra otros métodos de la clase [Array]:

// otros métodos de la clase Array
int[] numbers = [40, 10, 30, 20, 50];
Display("numbers", numbers);

// Reverse: invierte el orden de los elementos, en el mismo lugar
Array.Reverse(numbers);
Display("after Reverse", numbers);

// Sort sobre una parte del arreglo: 3 elementos a partir del índice 1
Array.Sort(numbers, 1, 3);
Display("after Sort(numbers, 1, 3)", numbers);

// Copy: copia de 3 elementos a otro arreglo
int[] copy = new int[5];
Array.Copy(numbers, copy, 3);
Display("copy", copy);

// Fill: llena el arreglo con un valor; Clear: restablece los elementos a su valor predeterminado
Array.Fill(copy, 7);
Display("after Fill(copy, 7)", copy);
Array.Clear(copy, 1, 2);
Display("after Clear(copy, 1, 2)", copy);

// IndexOf, LastIndexOf en un arreglo de cadenas
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")}");

// ordenamiento de un arreglo de cadenas: orden alfabético de la cultura actual
Array.Sort(colors);
Display("sorted colors", colors);

// un arreglo 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)}");

// visualización de un arreglo en una línea
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

Comentarios:

  • línea 6: [Reverse] invierte el orden de los elementos del propio arreglo;
  • línea 10: solo se ordenan 3 elementos a partir de la posición 1: 20, 30, 10 pasan a ser 10, 20, 30;
  • línea 15: copia los 3 primeros elementos de [numbers] en [copy], mientras que los demás elementos conservan su valor inicial de 0;
  • Líneas 19–21: [Fill] llena el arreglo; [Clear] restablece a 0 dos elementos a partir de la posición 1;
  • línea 29: las cadenas se ordenan alfabéticamente según la cultura actual;
  • Línea 34: para un arreglo bidimensional, [Rank] es 2, [Length] es el número total de elementos, y [GetLength(i)] es el número de elementos de la dimensión i;
  • Línea 39: [string.Join] muestra un arreglo en una sola línea.

LINQ, del que hablaremos más adelante, ofrece otras formas de buscar, ordenar o transformar los elementos de un arreglo.

5.4. Colecciones genéricas

Además de los arreglos, existen diversas clases para almacenar colecciones de elementos. Las colecciones genéricas, introducidas con .NET 2.0, se encuentran en el espacio de nombres [System.Collections.Generic], que forma parte de los espacios de nombres [using] implícitos. Presentaremos primero dos colecciones de uso frecuente —la lista y el diccionario— y luego veremos brevemente otras.

El espacio de nombres [System.Collections] contiene las versiones más antiguas, no genéricas, de estas colecciones, que datan de .NET 1.0: [ArrayList] (una lista), [Hashtable] (un diccionario)... El curso de 2008 todavía presentaba [ArrayList]. Estas clases están ahora obsoletas: almacenan referencias de tipo [object], lo que obliga a convertir los elementos leídos y a empaquetar (boxing) los números en objetos, con los costos asociados de memoria y tiempo. Las colecciones genéricas no tienen ninguno de estos inconvenientes: una *[List<int>] almacena sus enteros directamente en un arreglo interno *[int[]] , y el compilador verifica el tipo de los elementos agregados. [ArrayList] y [Hashtable] ya no deben usarse en código nuevo.

5.4.1. La clase genérica List<T>

La clase [System.Collections.Generic.List<T>] permite implementar colecciones de objetos [T] cuyo tamaño varía durante la ejecución del programa. Un objeto de tipo [List<T>] se maneja casi como un arreglo. Así, el elemento i de una lista [l] se denota [l[i]].

Para una lista de tipo [List<T>] donde [T] es una clase, la lista almacena referencias a objetos de tipo [T], como un arreglo de objetos; si [T] es un tipo de valor ([int], [double], estructura…), los propios valores se almacenan en la lista.

Estas son algunas de las propiedades y métodos de las listas genéricas.

Propiedades:

propiedad
función
[public int Count { get; }]
número de elementos de la lista
[public int Capacity { get; set; }]
Número de elementos que la lista puede contener antes de ampliarse. Esta ampliación se produce automáticamente. Este concepto de capacidad es análogo al descrito para la clase [StringBuilder]

Métodos:

Método
función
[public void Add(T item)]
agrega [item] al final de la lista
[public void AddRange(IEnumerable<T> collection)]
agrega los elementos de [collection] al final de la lista
[public int BinarySearch(T item)]
devuelve la posición de [item] en la lista ordenada si está presente; de lo contrario, devuelve un número negativo
[public void Clear()]
elimina todos los elementos de la lista
[public bool Contains(T item)]
devuelve [true] si [item] está en la lista; de lo contrario, [false]
[public List<T> GetRange(int index, int count)]
devuelve una nueva lista formada por [count] elementos a partir de la posición [index]
[public int IndexOf(T item)]
Devuelve la posición de [item] en la lista, o -1 si [item] no se encuentra
[public void Insert(int index, T item)]
inserta [item] en la posición [index] en la lista
[public bool Remove(T item)]
elimina la primera aparición de [item] de la lista; devuelve [true] si la operación tiene éxito y [false] en caso contrario
[public void RemoveAt(int index)]
elimina el elemento n.º [index] de la lista
[public void Reverse()]
invierte el orden de los elementos de la lista
[public void Sort()]
ordena la lista en orden natural; una versión sobrecargada recibe un [IComparer<T>]
[public T[] ToArray()]
devuelve los elementos de la lista como un arreglo

Retomemos el ejemplo que vimos antes con un arreglo y procesémoslo ahora con un objeto de tipo [List<double>]. Como la lista es similar a un arreglo, el código cambia muy poco. Este es el programa [collections-01.cs]:

// la clase List<T>: el programa arrays-01.cs reescrito con una lista

// lectura de los elementos de una lista escrita en el teclado
List<double> elements = Input();
// número de elementos y capacidad
Console.WriteLine($"The list has {elements.Count} elements and a capacity of {elements.Capacity} elements");
// visualización de la lista sin ordenar
Display("Unsorted list", elements);
// búsqueda lineal en la lista sin ordenar
Search(elements, SearchType.Linear);
// ordenamiento de la lista
elements.Sort();
// visualización de la lista ordenada
Display("Sorted list", elements);
// búsqueda binaria en la lista ordenada
Search(elements, SearchType.Binary);

// ingreso de los valores de la lista: devuelve la lista creada
static List<double> Input()
{
    // al inicio, la lista está vacía
    List<double> elements = new();
    // bucle de ingreso de los elementos de la lista
    while (true)
    {
        Console.Write($"Element (real) {elements.Count} of the list (nothing to finish): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // fin del ingreso si la cadena está vacía
        if (answer == "")
        {
            break;
        }
        // verificación del ingreso
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Incorrect input, try again");
            continue;
        }
        // un elemento más en la lista: crece por sí sola
        elements.Add(element);
    }
    return elements;
}

// método genérico para mostrar los elementos de cualquier secuencia
static void Display<T>(string text, IEnumerable<T> elements)
{
    Console.WriteLine(text.PadRight(50, '-'));
    foreach (T element in elements)
    {
        Console.WriteLine(element);
    }
}

// búsqueda en la lista de elementos escritos en el teclado
static void Search(List<double> elements, SearchType type)
{
    while (true)
    {
        Console.Write("Element searched for (nothing to stop): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // ¿terminó?
        if (answer == "")
        {
            break;
        }
        // verificación
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Error, try again...");
            continue;
        }
        // buscamos el elemento en la lista
        int i = type == SearchType.Binary
            ? elements.BinarySearch(element)    // lista ordenada
            : elements.IndexOf(element);        // lista cualquiera
        // visualización de la respuesta
        Console.WriteLine(i >= 0 ? $"Found at position {i}" : $"Not in the list ({i})");
    }
}

// tipo de búsqueda
enum SearchType { Linear, Binary }

Comentarios:

  • línea 22: la lista se crea vacía. [new()] (C# 9) es una forma abreviada de [new List<double>()]: el tipo se infiere de la declaración de la variable;
  • línea 40: ya no hay que manejar ninguna redimensión; la lista se amplía automáticamente;
  • línea 6: el número de elementos de la lista y su capacidad;
  • líneas 12, 75, 76: los métodos [Sort], [BinarySearch] y [IndexOf] ahora son métodos de instancia de la lista, mientras que los de [Array] son métodos estáticos;
  • líneas 46–51: el método genérico [Display<T>] recibe dos parámetros:
    • el primero es un texto que se escribe;
    • el segundo es un objeto que implementa la interfaz genérica [IEnumerable<T>]:
1
2
3
4
public interface IEnumerable<out T> : IEnumerable
{
    IEnumerator<T> GetEnumerator();
}

La estructura [foreach (T element in elements)] es válida para cualquier objeto [elements] que implemente la interfaz [IEnumerable<T>]. Los arreglos y las listas implementan esta interfaz. Por lo tanto, el método [Display] sirve para mostrar tanto arreglos como listas. Volveremos sobre esta interfaz, que está en el corazón de 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): 

Los resultados son los mismos que con el arreglo. La capacidad de la lista aquí es 4 (línea 7): partiendo de 0, aumentó a 4 en la primera adición; habría aumentado a 8 en la quinta adición, duplicándose como la de un [StringBuilder].

5.4.2. Métodos de List<T> y expresiones de colección

El programa [collections-02.cs] usa los demás métodos de la lista y las expresiones de colección de C# 12, que ya vimos con los arreglos en el capítulo 3:

// los principales métodos de List<T> y las expresiones de colección

// una lista inicializada con una expresión de colección (C# 12)
List<string> cities = ["Paris", "Lyon", "Angers"];
Display("start", cities);

// agregados
cities.Add("Nantes");                       // al final
cities.Insert(1, "Brest");                  // en la posición 1
cities.AddRange(["Lille", "Tours"]);        // varios elementos al final
Display("after Add, Insert, AddRange", cities);

// acceso por índice, lectura y escritura
cities[0] = "Marseille";
Console.WriteLine($"cities[0]={cities[0]}, cities[^1]={cities[^1]}, Count={cities.Count}");

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

// eliminaciones
bool removed = cities.Remove("Lyon");       // por valor
cities.RemoveAt(0);                         // por posición
Display($"after Remove ({removed}), RemoveAt(0)", cities);

// ordenamiento, inversión, rango 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);

// conversión a arreglo y viceversa
string[] array = cities.ToArray();
List<string> other = new(array);
Console.WriteLine($"array of {array.Length} elements, new list of {other.Count} elements");

// el operador .. (spread) inserta los elementos de una colección en otra
int[] small = [1, 2, 3];
List<int> numbers = [0, .. small, 10, .. small];
Display("numbers", numbers);
// la misma sintaxis crea un arreglo, una lista o una colección vacía
int[] empty = [];
Console.WriteLine($"empty.Length={empty.Length}");

// Clear vacía la 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

Comentarios:

  • línea 4: una expresión de colección [a, b, c] inicializa una lista como un arreglo;
  • líneas 8–10: tres formas de agregar elementos;
  • línea 14: el elemento n.º 0 es de lectura y escritura; [cities[^1]] es el último elemento, como con un arreglo;
  • línea 21: [Remove] devuelve [true] si el elemento se encontró y se eliminó;
  • línea 30: una nueva lista formada por 2 elementos a partir de la posición 1;
  • líneas 34–35: conversión de una lista a un arreglo, y de un arreglo (o de cualquier secuencia) a una lista;
  • línea 40: en una expresión de colección, el operador [..] (spread) inserta todos los elementos de otra colección;
  • Línea 43: [] designa una colección vacía del tipo esperado.

5.4.3. La clase Dictionary<TKey,TValue>

La clase [System.Collections.Generic.Dictionary<TKey,TValue>] se usa para implementar un diccionario. Un diccionario puede concebirse como un arreglo de dos columnas:

clave
valor
clave1
valor1
clave2
valor2
...
...

En la clase [Dictionary<TKey,TValue>], las claves son de tipo [TKey] y los valores son de tipo [TValue]. Las claves son únicas: no puede haber dos claves idénticas. Un diccionario de este tipo se vería así si los tipos [TKey] y [TValue] se refirieran a clases:

Image

El valor asociado a la clave [c] en un diccionario [d] se obtiene con la notación [d[c]]. Este valor es de lectura y escritura. Así, podemos escribir:

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

Al escribir, [d[c] = v] agrega el par (c, v) si la clave [c] no existe, y reemplaza el valor asociado a [c] en caso contrario. Al leer, si la clave [c] no existe en el diccionario [d], la notación [d[c]] lanza una excepción [KeyNotFoundException].

Los principales métodos y propiedades de la clase [Dictionary<TKey,TValue>] son los siguientes.

Propiedades:

propiedad
función
[public int Count { get; }]
número de entradas (clave, valor) del diccionario
[public KeyCollection Keys { get; }]
colección de las claves del diccionario
[public ValueCollection Values { get; }]
colección de los valores del diccionario

Métodos:

Método
Función
[public void Add(TKey key, TValue value)]
Agrega el par (clave, valor) al diccionario; lanza una excepción si la clave ya existe
[public bool TryAdd(TKey key, TValue value)]
Igual que el anterior, pero devuelve [false] en lugar de lanzar una excepción
[public void Clear()]
elimina todos los pares del diccionario
[public bool ContainsKey(TKey key)]
Devuelve [true] si [key] es una clave del diccionario; de lo contrario, devuelve [false]
[public bool ContainsValue(TValue value)]
devuelve [true] si [value] es un valor del diccionario, y [false] en caso contrario
[public bool Remove(TKey key)]
elimina el par clave-valor [key] del diccionario; devuelve [true] si la operación tiene éxito y [false] en caso contrario
[public bool TryGetValue(TKey key, out TValue value)]
devuelve [true] y asigna a [value] el valor asociado a la clave [key] si esta existe; devuelve [false] en caso contrario, y [value] recibe el valor predeterminado del tipo [TValue]

Consideremos el programa de ejemplo [collections-03.cs]:

// la clase Dictionary<TKey,TValue>

// creación de un diccionario <string,int> a partir de un arreglo de cadenas "nombre:edad"
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 del diccionario
Console.WriteLine($"The dictionary has {dico.Count} elements");
// lista de claves
Display("[List of keys]", dico.Keys);
// lista de valores
Display("[List of values]", dico.Values);
// lista de claves y valores
Console.WriteLine("[List of keys & values]");
foreach (string key in dico.Keys)
{
    Console.WriteLine($"key={key} value={dico[key]}");
}
// eliminamos la clave "paul"
Console.WriteLine("[Removal of a key]");
dico.Remove("paul");
// recorrido de los pares (clave, valor) con deconstrucción
Console.WriteLine("[List of keys & values]");
foreach (var (key, value) in dico)
{
    Console.WriteLine($"key={key} value={value}");
}
// Add rechaza una clave existente, mientras que dico[key] = value la reemplaza
try
{
    dico.Add("jean", 21);
}
catch (ArgumentException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}
// TryAdd solo agrega si la clave está ausente
Console.WriteLine($"TryAdd(\"jean\", 21)={dico.TryAdd("jean", 21)}, TryAdd(\"zoé\", 12)={dico.TryAdd("zoé", 12)}");
// la notación dico[key] lanza una excepción si la clave está ausente
try
{
    Console.WriteLine(dico["x"]);
}
catch (KeyNotFoundException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}

// búsqueda en el diccionario
while (true)
{
    Console.Write("Name searched for (nothing to stop): ");
    string searchedName = (Console.ReadLine() ?? "").Trim();
    if (searchedName == "")
    {
        break;
    }
    // TryGetValue devuelve true si la clave existe y coloca el valor asociado en age
    if (dico.TryGetValue(searchedName, out int age))
    {
        Console.WriteLine($"{searchedName},{age}");
    }
    else
    {
        Console.WriteLine($"Name {searchedName} unknown");
    }
}

// método genérico para mostrar los elementos de una secuencia
static void Display<T>(string text, IEnumerable<T> elements)
{
    Console.WriteLine(text.PadRight(50, '-'));
    foreach (T element in elements)
    {
        Console.WriteLine(element);
    }
}

Comentarios:

  • línea 4: un arreglo de cadenas que se usará para inicializar el diccionario <string,int>;
  • línea 5: el diccionario, que está vacío;
  • líneas 6–9: su inicialización a partir del arreglo de cadenas;
  • línea 12: el número de entradas del diccionario;
  • líneas 14–16: las claves y los valores del diccionario. [dico.Keys] y [dico.Values] implementan [IEnumerable<T>]: el método [Display] que ya vimos es adecuado;
  • línea 25: eliminación de una entrada del diccionario;
  • línea 28: un diccionario es una secuencia de pares [KeyValuePair<TKey,TValue>], cada uno de los cuales tiene una propiedad [Key] y una propiedad [Value]. Desde .NET Core 2.0, un par de este tipo se descompone en dos variables, como una tupla (capítulo 3);
  • líneas 35–42: [Add] rechaza una clave existente lanzando una excepción; [TryAdd] devuelve [false] en ese caso. Los mensajes de excepción de .NET están en inglés: .NET 10 no ofrece mensajes en francés;
  • línea 46: intentar leer una clave inexistente lanza una excepción [KeyNotFoundException];
  • línea 63: búsqueda de una clave en el diccionario. [TryGetValue] devuelve [true] si la clave existe. El curso de 2008 ignoraba este resultado y verificaba si el valor devuelto era null, una técnica que funcionaba solo porque el valor 0 no estaba en el diccionario. Verificar el valor booleano devuelto es el enfoque correcto.

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): 

Aquí las claves aparecen en el orden en que se agregaron, pero esto no está garantizado: un *[Dictionary]* no conserva ningún orden. Tras las eliminaciones, un nuevo elemento puede ocupar el lugar de uno eliminado. Si el orden de las claves es importante, use un *[SortedDictionary]*, que se muestra más adelante.

5.4.4. Otras colecciones genéricas

El espacio de nombres [System.Collections.Generic] contiene otras colecciones, cada una adecuada para un propósito específico:

clase
función
[HashSet<T>]
un conjunto: sin duplicados, sin orden, prueba de pertenencia muy rápida; operaciones de conjuntos (unión, intersección, diferencia)
[SortedSet<T>]
un conjunto cuyos elementos se mantienen ordenados
[Queue<T>]
una cola: los elementos salen en el orden en que se insertaron (FIFO, first in, first out)
[Stack<T>]
una pila: el último elemento agregado es el primero en salir (LIFO, last in first out)
[SortedDictionary<TKey,TValue>]
un diccionario cuyas claves se mantienen ordenadas
[PriorityQueue<TElement,TPriority>]
una cola de prioridad (.NET 6): el elemento que se extrae es el de menor prioridad
[LinkedList<T>]
una lista doblemente enlazada: inserciones y eliminaciones rápidas en medio de la lista

El programa [collections-04.cs] ofrece una visión rápida:

// un panorama de otras colecciones genéricas

// HashSet<T>: un conjunto, sin duplicados ni orden
HashSet<string> languages = ["C#", "Java", "PHP"];
bool added1 = languages.Add("Python");
bool added2 = languages.Add("Java");             // ya presente: rechazado
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);                        // intersección
Console.WriteLine($"HashSet : intersection = {{{string.Join(", ", common)}}}");
common.UnionWith(["Go"]);                         // unión
Console.WriteLine($"HashSet : after union = {{{string.Join(", ", common)}}}");

// Queue<T>: una cola, el primero en entrar es el primero en salir
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>: una pila, el último en entrar es el primero en salir
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 la excepción en una pila vacía
stack.Pop();
Console.WriteLine($"Stack : TryPop on an empty stack = {stack.TryPop(out int top)}");

// SortedDictionary<TKey,TValue>: un diccionario cuyas claves se mantienen ordenadas
SortedDictionary<string, int> ages = new()
{
    ["violette"] = 15,
    ["jean"] = 20,
    ["mélanie"] = 10,
    ["paul"] = 18
};
Console.WriteLine($"SortedDictionary : {string.Join(", ", ages)}");

// PriorityQueue<TElement,TPriority>: el elemento de menor prioridad siempre sale primero
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)

Comentarios:

  • línea 4: las expresiones de colección también inicializan un conjunto;
  • línea 6: [Add] devuelve [false] si el elemento ya está en el conjunto, que permanece sin cambios;
  • Líneas 9–12: [IntersectWith] y [UnionWith] modifican el conjunto; por lo tanto, se trabaja sobre una copia de [languages]. El orden en que se muestran los elementos de un conjunto no tiene significado (línea 4);
  • las llaves dobles [{{] y [}}] en una cadena interpolada muestran una sola llave;
  • líneas 16–20: [Enqueue] encola un elemento, [Dequeue] desencola el elemento más antiguo, [Peek] obtiene el elemento sin desencolarlo;
  • líneas 23–30: [Push] apila un elemento, [Pop] extrae el elemento más reciente. [Pop] sobre una pila vacía lanza una excepción; [TryPop] devuelve [false];
  • líneas 33–40: un diccionario inicializado con la sintaxis [[key] = value]; sus pares clave-valor se enumeran en orden de clave;
  • líneas 43–49: cada elemento entra en la cola con una prioridad; los pacientes salen en orden ascendente de prioridad, sin importar su orden de llegada.

5.4.5. Colecciones de solo lectura

Una clase que gestiona una colección suele necesitar exponerla hacia el exterior sin permitir que se modifique. .NET ofrece para ello interfaces de solo lectura: [IReadOnlyCollection<T>] (un [Count] y un [foreach]), [IReadOnlyList<T>] (más el acceso por índice) e [IReadOnlyDictionary<TKey,TValue>]. Las clases [List<T>], [T[]], y [Dictionary<TKey,TValue>] las implementan. El programa [collections-05.cs] las utiliza:

// colecciones de solo lectura

var classroom = new Classroom();
classroom.Enroll("dupont");
classroom.Enroll("martin");
// el código externo puede leer la lista de estudiantes...
IReadOnlyList<string> students = classroom.Students;
Console.WriteLine($"{students.Count} students: {string.Join(", ", students)}, students[0]={students[0]}");
// ... pero la interfaz IReadOnlyList<T> no tiene Add ni Remove: students.Add("x") no compila

// una conversión (cast) a List<string> permitiría eludir la protección
if (students is List<string> list)
{
    Console.WriteLine("Students is actually a modifiable List<string>");
}
// AsReadOnly devuelve un envoltorio de solo lectura que no se puede eludir
IReadOnlyList<string> protectedList = classroom.ProtectedStudents;
Console.WriteLine($"ProtectedStudents is of type {protectedList.GetType().Name}");
try
{
    // ReadOnlyCollection<T> implementa IList<T>, pero sus métodos de modificación lanzan una excepción
    ((IList<string>)protectedList).Add("intruder");
}
catch (NotSupportedException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}
// el envoltorio refleja las modificaciones hechas por la clase propietaria
classroom.Enroll("durand");
Console.WriteLine($"{protectedList.Count} students: {string.Join(", ", protectedList)}");

// un diccionario de solo lectura
IReadOnlyDictionary<string, int> grades = new Dictionary<string, int> { ["dupont"] = 12, ["martin"] = 15 };
Console.WriteLine($"grades[martin]={grades["martin"]}, ContainsKey(durand)={grades.ContainsKey("durand")}");

// una clase que conserva el control de su lista
class Classroom
{
    // la lista es privada: solo la clase puede modificarla
    private readonly List<string> _students = [];

    // expuesta como solo lectura mediante una interfaz
    public IReadOnlyList<string> Students => _students;
    // expuesta mediante un envoltorio de solo lectura
    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

Comentarios:

  • líneas 37–47: la clase [Classroom] gestiona una lista de estudiantes. La lista en sí es privada; solo el método [Enroll] permite modificarla;
  • línea 43: la propiedad [Students] convierte la lista al tipo [IReadOnlyList<string>], que solo admite operaciones de lectura: [students.Add("x")] provocaría un error de compilación;
  • línea 12: sin embargo, esta protección es solo superficial: el objeto devuelto es la propia lista, y una conversión de tipo (cast) permite acceder a sus métodos de modificación;
  • línea 45: [AsReadOnly] envuelve la lista en un contenedor de tipo [ReadOnlyCollection<T>]. Esta vez no es posible ninguna modificación: sus métodos de modificación, impuestos por la interfaz [IList<T>], lanzan una excepción [NotSupportedException] (línea 5). El envoltorio no copia la lista: ve las modificaciones realizadas por la clase propietaria (línea 6);
  • línea 33: un diccionario visto a través de la interfaz [IReadOnlyDictionary<TKey,TValue>].

Para los datos que nunca deben cambiar después de su creación, el espacio de nombres [System.Collections.Immutable] ofrece colecciones inmutables ([ImmutableList<T>], [ImmutableDictionary<TKey,TValue>]…) y [System.Collections.Frozen] ofrece colecciones congeladas optimizadas para lectura ([FrozenDictionary<TKey,TValue>], .NET 8). No entraremos en detalles sobre ellas.

5.5. LINQ

El curso de 2008 terminaba justo antes de LINQ, presentando sus tipos anónimos sin utilizarlos realmente. LINQ (Language Integrated Query, C# 3, 2007) es un conjunto de métodos que permiten consultar una colección tal como se consulta una base de datos: filtrar, ordenar, agrupar, calcular totales, etc. Se aplica a cualquier colección que implemente la interfaz [IEnumerable<T>]: arreglos, listas, diccionarios, conjuntos, líneas de un archivo, resultados de una expresión regular y, con Entity Framework Core (capítulo 11), tablas de bases de datos. El espacio de nombres [System.Linq] forma parte de los espacios de nombres [using] implícitos.

5.5.1. Las secuencias IEnumerable<T> y los iteradores

Una colección que implementa [IEnumerable<T>] se denomina secuencia: se puede recorrer con [foreach]. La interfaz contiene un único método, [GetEnumerator], que devuelve un enumerador [IEnumerator<T>]: un objeto que recorre la secuencia ([MoveNext]) y devuelve el elemento actual ([Current]).

Un método puede producir una secuencia sin construir una colección: es un iterador. Devuelve sus elementos uno por uno mediante la instrucción [yield return]. El programa [linq-01.cs] ofrece dos ejemplos:

// secuencias IEnumerable<T> e iteradores (yield return)

// 1 - foreach sobre una secuencia producida por un iterador
Console.WriteLine("[foreach on Evens(6)]");
foreach (int n in Evens(6))
{
    Console.WriteLine($"  received {n}");
}

// 2 - lo que hace foreach: le pide un enumerador a la secuencia
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 - una secuencia infinita: se produce solo a medida que se necesita
Console.WriteLine("[infinite sequence]");
foreach (long f in Fibonacci())
{
    if (f > 100)
    {
        break;
    }
    Console.Write($"{f} ");
}
Console.WriteLine();

// 4 - un arreglo, una lista y una cadena también son IEnumerable<T>
IEnumerable<char> letters = "abc";
IEnumerable<string> words = new List<string> { "one", "two" };
Console.WriteLine($"[other sequences] {string.Join("-", letters)} {string.Join("-", words)}");

// los 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})");
        // devolvemos i al código llamador; continuaremos aquí en la siguiente solicitud
        yield return i;
    }
    Console.WriteLine("  (end of the iterator)");
}

// la sucesión de Fibonacci, sin fin
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

Comentarios:

  • Líneas 39–48: el método [Evens] es un iterador: su tipo de retorno es *[IEnumerable<int>], y contiene la instrucción [yield return] (línea 46). No construye ninguna lista: por cada [yield return], devuelve un elemento al código que lo recorre y se pausa*; se reanudará en la instrucción siguiente cuando se le pida el siguiente elemento;
  • líneas 5–7: los resultados (líneas 3–12) muestran que la producción de un elemento por el iterador y su consumo por el bucle [foreach] se alternan;
  • líneas 12–17: lo que [foreach] hace realmente: solicita un enumerador a la secuencia, llama a [MoveNext] mientras ese método devuelva [true] y lee el elemento actual de [Current]. El iterador se libera al final mediante la instrucción [using] (volveremos sobre esto al hablar de los archivos). Observe que la llamada a [Evens(4)] en la línea 12 no hace nada: el mensaje “start of the iterator” solo aparece en la primera llamada a [MoveNext];
  • líneas 52–58: un iterador puede producir una secuencia infinita; calcula solo los elementos solicitados. Es el bucle [foreach] el que decide cuándo detenerse (línea 25). La línea 58 usa las tuplas del capítulo 3 para intercambiar valores;
  • líneas 34–35: una cadena es una secuencia de caracteres; una lista es una secuencia de sus elementos. Aquí la lista se crea con la sintaxis [new List<string> { ... }] de inicializador de colección (C# 3), que se encuentra con frecuencia en el código existente.

Este mecanismo de generación bajo demanda lo utilizan todos los métodos de LINQ.

5.5.2. Filtrar, proyectar, ordenar

Los ejemplos siguientes trabajan con una pequeña lista de personas. Una persona se representa mediante un [record] (C# 9), es decir, un record presentado en el capítulo 4: en una sola línea, se obtiene una clase con un constructor, propiedades de solo lectura, un método [ToString] que muestra las propiedades y un operador de igualdad que compara los valores de las propiedades.

El programa [linq-02.cs] muestra los métodos básicos de LINQ:

// LINQ: filtrado (Where), proyección (Select), ordenamiento (OrderBy, ThenBy)

// los datos: una lista de personas
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: los adultos; p => p.Age >= 18 es una función anónima
IEnumerable<Person> adults = persons.Where(p => p.Age >= 18);
Display("[Where: the adults]", adults);

// Select: una proyección, aquí cada persona se convierte en una cadena
IEnumerable<string> names = persons.Select(p => $"{p.FirstName} {p.LastName.ToUpper()}");
Display("[Select: first name LAST NAME]", names);

// los operadores se pueden encadenar: los nombres de las personas de Angers, en orden alfabético
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);

// ordenamiento por varios criterios: edad descendente, luego apellido ascendente
var sorted = persons.OrderByDescending(p => p.Age).ThenBy(p => p.LastName);
Display("[OrderByDescending + ThenBy]", sorted);

// la misma consulta que 'angersPeople' escrita con la sintaxis 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 también puede proporcionar la posición del elemento
var numbered = persons.Take(3).Select((p, i) => $"{i + 1}. {p.LastName}");
Display("[Select with index]", numbered);

// visualización de una secuencia
static void Display<T>(string title, IEnumerable<T> sequence)
{
    Console.WriteLine(title);
    foreach (T element in sequence)
    {
        Console.WriteLine($"  {element}");
    }
}

// una persona
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

Comentarios:

  • líneas 4–13: la lista de personas, inicializada mediante una expresión de colección; [new(...)] crea un objeto del tipo esperado, en este caso [Person];
  • línea 56: el record [Person]. Una aplicación de un solo archivo coloca sus declaraciones de tipos después de las instrucciones de nivel superior;
  • línea 16: el método [Where] filtra la secuencia: solo conserva los elementos que cumplen una condición. Esta condición se le pasa en forma de función anónima [p => p.Age >= 18], que se lee “la función que, para una persona p, asocia el booleano p.Age >= 18”. Esta notación se denomina expresión lambda. [Where] llama a esta función para cada persona. Las lambdas se estudiarán en detalle en el capítulo 7 (“Delegados, lambdas y eventos”; por ahora basta con saber leerlas);
  • El resultado de [Where] es una nueva secuencia, [IEnumerable<Person>]: la lista [persons] permanece sin cambios. Esto vale para todos los métodos de LINQ;
  • el método [Display] muestra cada persona mediante el método [ToString] generado para el record: [Person { LastName = dupont, ... }];
  • Línea 20: el método [Select] transforma cada elemento de la secuencia en un nuevo valor, en este caso una cadena. El resultado es una secuencia [IEnumerable<string>];
  • líneas 24–27: los métodos de LINQ devuelven secuencias, a las que se pueden aplicar otros métodos de LINQ. Los métodos suelen escribirse uno por línea: esta cadena de llamadas se lee de arriba abajo como una receta;
  • línea 26: [OrderBy] ordena la secuencia según la clave devuelta por la lambda, en este caso el nombre;
  • línea 31: [OrderByDescending] ordena en orden descendente; [ThenBy] (o [ThenByDescending]) agrega un criterio secundario, que sirve para distinguir los elementos iguales según el primer criterio: Durand y Laurent, que tienen ambos 32 años, se ordenan por nombre (líneas 23–24);
  • líneas 35–38: la misma consulta que [angersPeople] escrita con la sintaxis de consulta, similar a SQL. El compilador la traduce exactamente a la cadena de llamadas [Where(...).OrderBy(...).Select(...)]: las dos notaciones son equivalentes. La sintaxis de consulta es más legible para uniones y agrupaciones; la sintaxis de métodos es más común y es la única que da acceso a todos los métodos de LINQ ([Take], [Count], [First]…);
  • Línea 42: una variante de [Select] pasa a la lambda el elemento y su posición en la secuencia.

5.5.3. Cuantificadores, agregados, selección de elementos

El programa [linq-03.cs] incluye métodos que devuelven un único valor y métodos que seleccionan una porción de la secuencia:

// LINQ: cuantificadores, agregados, elección de elementos, particiones

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"),
];

// cuantificadores: Any (al menos uno), 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 devuelven el propio elemento y no el valor mínimo o máximo
Console.WriteLine($"MinBy(age)={persons.MinBy(p => p.Age)?.LastName}, MaxBy(age)={persons.MaxBy(p => p.Age)?.LastName}");

// elección de un 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 exactamente un elemento
    _ = persons.Single(p => p.City == "Angers");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"Single(Angers) : {e.GetType().Name} : {e.Message}");
}
try
{
    // First exige al menos un elemento
    _ = persons.First(p => p.City == "Brest");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"First(Brest) : {e.GetType().Name} : {e.Message}");
}

// Distinct: elimina los duplicados
var cities = persons.Select(p => p.City).Distinct();
Console.WriteLine($"Distinct(cities)=[{string.Join(", ", cities)}]");
// DistinctBy: un elemento por valor de clave
var onePerCity = persons.DistinctBy(p => p.City).Select(p => p.LastName);
Console.WriteLine($"DistinctBy(city)=[{string.Join(", ", onePerCity)}]");

// particiones: 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: división en paquetes de tamaño fijo (paginación)
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

Comentarios:

  • Línea 15: [Any] devuelve [true] si al menos un elemento cumple la condición, y [All] si todos la cumplen. Sin parámetros, [Any] indica si la secuencia no está vacía;
  • Líneas 18–20: los agregados [Count], [Sum], [Average], [Min], [Max] calculan un valor a partir de toda la secuencia. [Count] acepta una condición (una lista también tiene una propiedad [Count], que se prefiere al método cuando no hay condición); [Sum], [Average], [Min] y [Max] aceptan una lambda que especifica el valor que se debe considerar para cada elemento;
  • Línea 22: [MinBy] y [MaxBy] (.NET 6) devuelven el elemento (en este caso, la persona) cuya clave es mínima o máxima, y no el valor de la clave en sí. Para una secuencia vacía de objetos (tipo de referencia), devuelven [null], de ahí el operador [?.];
  • línea 25: [First] devuelve el primer elemento de la secuencia, o el primero que cumple una condición; [Last] devuelve el último;
  • Línea 26: si ningún elemento coincide, [First] lanza una excepción (línea 11 de los resultados), mientras que [FirstOrDefault] devuelve el valor predeterminado del tipo, en este caso [null];
  • Línea 28: [Single] devuelve el único elemento que cumple la condición y lanza una excepción si hay cero o varios (línea 10). Se usa cuando la unicidad es una regla de los datos, como al buscar un elemento por su clave. [SingleOrDefault] devuelve el valor predeterminado si no hay ningún elemento;
  • línea 32: el resultado de la llamada no se utiliza; se asigna al descarte [_] (C# 7) para señalarlo;
  • línea 49: [Distinct] elimina los duplicados; [DistinctBy] (.NET 6) conserva el primer elemento de cada valor de clave;
  • líneas 57–58: [Take(n)] conserva los primeros n elementos, [Skip(n)] los omite. Combinados, extraen una “página” de resultados. [TakeWhile] conserva los elementos mientras se cumple una condición y se detiene en el primer elemento que no la cumple;
  • línea 62: [Chunk] (.NET 6) divide la secuencia en arreglos de 3 elementos, el último de los cuales puede ser más corto;
  • línea 64: la variable [page] se incrementa después de usarse en la interpolación.

5.5.4. Tipos anónimos, agrupaciones, uniones

El programa [linq-04.cs] presenta los tipos anónimos y operaciones más complejas:

// LINQ: tipos anónimos, agrupaciones, combinaciones (joins), conversiones

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 - un tipo anónimo: un objeto cuyo tipo, sin nombre, es creado por el compilador
var p1 = new { LastName = "dupont", Age = 45 };
Console.WriteLine($"[anonymous type] {p1}, p1.LastName={p1.LastName}");
// Select hacia un tipo anónimo: solo conservamos las propiedades útiles
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: agrupación de las personas por ciudad
Console.WriteLine("[GroupBy]");
foreach (IGrouping<string, Person> group in persons.GroupBy(p => p.City))
{
    // un grupo tiene una clave (Key) y es en sí mismo una secuencia de personas
    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: asociación de personas y ciudades según el nombre de la ciudad
Console.WriteLine("[Join]");
var join = persons.Join(cities,
    p => p.City,                                     // clave del lado de las personas
    c => c.Name,                                     // clave del lado de las ciudades
    (p, c) => new { p.LastName, c.Department });     // lo que conservamos de un par
foreach (var j in join)
{
    Console.WriteLine($"  {j.LastName} lives in the department {j.Department}");
}
// la misma combinación en sintaxis de consulta: Lyon, ausente de la lista de ciudades, también 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 - conversiones: 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

Comentarios:

  • Línea 22: un tipo anónimo (C# 3): la expresión [new { LastName = ..., Age = ... }] crea un objeto cuya clase sin nombre es generada por el compilador con dos propiedades de solo lectura, [LastName] y [Age]. Como este tipo no tiene nombre, la variable debe declararse como [var]. Sin embargo, el compilador conoce perfectamente este tipo: [p1.LastName] se valida en tiempo de compilación, y el editor sugiere las propiedades de [p1] en el autocompletado;
  • línea 25: el uso principal de los tipos anónimos: en un [Select], conservar solo los datos útiles sin tener que declarar una clase para ellos. [p.LastName] es una abreviatura de [LastName = p.LastName];
  • Línea 33: [GroupBy] agrupa los elementos que tienen la misma clave. El resultado es una secuencia de grupos [IGrouping<TKey,TElement>]: cada grupo tiene una propiedad [Key], el valor común de la clave, y es a su vez la secuencia de los elementos del grupo, a la que se pueden aplicar [Count], [Average], [Select]… (línea 36);
  • líneas 41–44: [Join] asocia cada persona con la ciudad del mismo nombre. Sus parámetros son la segunda secuencia, la clave de unión de cada lado y una lambda que construye el resultado a partir de un par (persona, ciudad). Como un join de SQL, [Join] solo conserva los pares que coinciden: Laurent, que vive en Lyon —ausente de la lista de ciudades—, no aparece, ni tampoco Brest, que no tiene residentes;
  • líneas 50–53: la unión en sintaxis de consulta, que es más legible: [join ... in ... on ... equals ...]. Se le agrega un filtro, [where]. La sintaxis de consulta incluye también una cláusula, [group ... by ...], para las agrupaciones;
  • línea 57: [ToList] (y [ToArray]) ejecuta la consulta y almacena sus resultados en una lista (un arreglo);
  • línea 58: [ToDictionary] construye un diccionario: la primera lambda proporciona la clave de cada elemento, la segunda su valor. Una clave duplicada provoca una excepción;
  • Línea 63: [CountBy] (.NET 9) cuenta los elementos de cada valor de clave. Devuelve una secuencia de pares [KeyValuePair<string,int>]. Es un atajo para [GroupBy(p => p.City).Select(g => (g.Key, g.Count()))];
  • Línea 68: [AggregateBy] (.NET 9) acumula un valor para cada valor de clave: partiendo de 0, para cada persona, su edad se suma al total de su ciudad. Las tuplas devueltas se descomponen en el bucle [foreach];
  • línea 73: [Index] (.NET 9) asocia cada elemento con su posición en la secuencia, en forma de tupla (posición, elemento).

5.5.5. Ejecución diferida

Una consulta LINQ no se ejecuta cuando se escribe, sino cuando se recorre su resultado: esta es la ejecución diferida. El programa [linq-05.cs] lo demuestra mediante lambdas que muestran lo que están haciendo:

// LINQ: ejecución diferida

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

// 1 - definir una consulta no la ejecuta
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 - se ejecuta cuando se itera sobre ella, elemento por elemento
Console.WriteLine("[foreach]");
foreach (int c in evenSquares)
{
    Console.WriteLine($"  foreach receives {c}");
}

// 3 - la consulta se vuelve a evaluar en cada iteración: ve las modificaciones del origen
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 ejecuta la consulta de inmediato y almacena el 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 - los agregados (Count, Sum, First...) también se ejecutan de inmediato
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 detiene la iteración en cuanto encuentra un 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

Comentarios:

  • Líneas 7–16: una consulta que selecciona los números pares y luego calcula sus cuadrados. Aquí las lambdas se escriben con un cuerpo entre llaves, que muestra un mensaje antes de devolver su valor mediante [return];
  • Línea 3 de los resultados: después de definir la consulta, no se mostró nada: ni [Where] ni [Select] ha examinado aún ningún elemento. [evenSquares] no contiene resultados, sino una descripción de un cálculo;
  • Líneas 4–16: la consulta se ejecuta durante el bucle [foreach], elemento por elemento: cada número pasa por [Where], luego por [Select] si es par, y después entra en el bucle antes de que se examine el número siguiente. Son iteradores, como [Evens] en [linq-01.cs];
  • líneas 28–31: la consulta [large] se reevalúa en cada recorrido: tiene en cuenta el número 10 agregado a la lista después de su definición;
  • línea 34: [ToList] ejecuta la consulta de inmediato y almacena sus resultados: [snapshot] es una lista que no ve la adición de 20 (línea 19);
  • línea 39: los métodos que devuelven un único valor ([Count], [Sum], [First], [Any]…) también recorren la secuencia de inmediato;
  • líneas 45–49: [First] deja de iterar en cuanto encuentra un elemento: los números posteriores al 3 nunca se examinan.

La ejecución diferida tiene dos consecuencias prácticas:

  • una consulta que se recorre varias veces se ejecuta varias veces. Si su cálculo es costoso, o si se desea un resultado fijo, se convierte de una vez por todas con [ToList] o [ToArray];
  • las consultas pueden componerse sin costo: encadenar [Where], [Select] y [Take] no crea ninguna colección intermedia, y solo se calculan los elementos necesarios.

Encontraremos LINQ a lo largo de todo el curso, y veremos en el capítulo 7 cómo se construyen sus métodos.

5.6. Archivos de texto

Las clases de lectura y escritura de archivos se encuentran en el espacio de nombres [System.IO], que forma parte de los espacios de nombres [using] implícitos.

5.6.1. La clase StreamReader

La clase [System.IO.StreamReader] permite leer el contenido de un archivo de texto. En realidad, es capaz de manejar flujos que no son archivos (una conexión de red, por ejemplo). Estas son algunas de sus propiedades y métodos.

Constructores:

constructor
función
[public StreamReader(string path)]
Crea un flujo de lectura a partir del archivo de la ruta [path]. El contenido del archivo puede estar codificado de diversas maneras; por defecto se usa la codificación UTF-8. Otra sobrecarga permite especificar la codificación: [new StreamReader(path, Encoding.Latin1)]

Propiedades:

propiedad
función
[public bool EndOfStream { get; }]
[true] si el flujo se ha leído por completo

Métodos:

Método
Función
[public void Dispose()]
Cierra el flujo y libera los recursos asignados para su gestión. Esto debe hacerse después de procesar el flujo, lo cual se encarga de hacer la instrucción [using]. [Close] hace lo mismo
[public int Peek()]
devuelve el siguiente carácter del flujo sin consumirlo; -1 al final del flujo
[public int Read()]
devuelve el siguiente carácter del flujo y avanza un carácter; -1 al final del flujo
[public string? ReadLine()]
devuelve la siguiente línea del flujo, sin el carácter de fin de línea, o [null] si se está al final del flujo
[public string ReadToEnd()]
devuelve el resto del flujo, o "" si se está al final del flujo

El programa [files-01.cs] es el siguiente:

// lectura de un archivo de texto con StreamReader

// la carpeta actual: es donde se buscan los archivos designados con un nombre relativo
Console.WriteLine($"Current folder: {Path.GetFileName(Environment.CurrentDirectory)}");
// el nombre del archivo puede pasarse como argumento; de lo contrario infos.txt
string fileName = args.Length > 0 ? args[0] : "infos.txt";
try
{
    // lectura 1: línea por línea
    Console.WriteLine("Reading 1----------------");
    using (var stream = new StreamReader(fileName))
    {
        string? line;
        // ReadLine devuelve null al final del archivo
        while ((line = stream.ReadLine()) != null)
        {
            Console.WriteLine(line);
        }
    } // aquí se cierra el flujo

    // lectura 2: todo el archivo de una vez, con una declaración using
    Console.WriteLine("Reading 2----------------");
    using var stream2 = new StreamReader(fileName);
    Console.Write(stream2.ReadToEnd());
    // stream2 se cerrará al final del bloque que contiene su declaración, aquí el bloque try
}
catch (FileNotFoundException e)
{
    // e.FileName es la ruta completa del archivo; solo mostramos su nombre
    Console.WriteLine($"{e.GetType().Name} : the file [{Path.GetFileName(e.FileName)}] does not exist");
}
catch (IOException e)
{
    // los demás errores de entrada-salida
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}

Comentarios:

  • línea 4: muestra el nombre del directorio actual, aquel desde el cual se lanzó el comando [dotnet run]. Solo se muestra el último elemento de la ruta, con [Path.GetFileName], para no saturar los resultados con una ruta completa;
  • línea 6: el archivo leído es [infos.txt] o el que se pasa como argumento. Como es una ruta relativa, se busca en la carpeta actual;
  • línea 11: la estructura [using (stream = ...) { ... }] garantiza que el flujo se cierre al terminar el bloque, incluso si se produce una excepción dentro del bloque. Esto elimina la necesidad de llamar explícitamente al método de cierre. Se aplica a cualquier objeto que implemente la interfaz [IDisposable] —es decir, cualquier objeto con un método [Dispose] que libera recursos (archivo, conexión de red, conexión a base de datos, etc.);
  • líneas 15–17: el archivo se lee línea por línea. La asignación [line = stream.ReadLine()] es una expresión cuyo valor es el de [line]: se compara con [null], que indica el fin del archivo. La variable [line] es de tipo [string?]: [ReadLine] puede devolver [null];
  • línea 23: una declaración using (C# 8). Ya no hay bloque: la variable [stream2] se liberará al final del bloque que contiene su declaración, en este caso el bloque *[try]*. Esta sintaxis más concisa es la más habitual hoy en día;
  • línea 24: el archivo se lee de una sola vez;
  • líneas 27–32: los errores de E/S se señalan mediante excepciones derivadas de [IOException]*. *[FileNotFoundException]* es una de esas excepciones; por lo tanto, se captura primero. Su propiedad *[FileName] contiene la ruta completa del archivo buscado.

El archivo [infos.txt] es el siguiente:

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

Se encuentra en la carpeta [05-classes-dotnet], desde la cual se ejecuta el programa:

> 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

Con un archivo 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

Seleccionar la carpeta actual para ubicar los archivos de datos es el enfoque natural para una aplicación de un solo archivo que se ejecuta desde su propia carpeta. En un proyecto, el ejecutable se encuentra en una subcarpeta llamada [bin/Debug/net10.0] dentro del proyecto: veremos en la aplicación de ejemplo cómo copiar allí los archivos de datos y cómo ubicarlos.

5.6.2. La clase StreamWriter

La clase [System.IO.StreamWriter] permite escribir en un archivo de texto. Como la clase [StreamReader], en realidad es capaz de manejar flujos que no son archivos. Estas son algunas de sus propiedades y métodos.

Constructores:

constructor
función
[public StreamWriter(string path)]
crea un flujo de escritura hacia el archivo de la ruta [path]. El archivo se crea, o se sobrescribe si existe. Por defecto, el texto se codifica en UTF-8, sin BOM (véase más adelante)
[public StreamWriter(string path, bool append)]
Si [append] es igual a [true], las escrituras se agregan al final del archivo existente

Propiedades:

propiedad
función
[public bool AutoFlush { get; set; }]
define el modo de escritura en el archivo. Si [AutoFlush] es igual a [false] (valor predeterminado), la escritura en el flujo no es inmediata: el texto se escribe primero en un búfer, y luego en el archivo cuando el búfer está lleno, cuando se vacía explícitamente con el método [Flush] o cuando se cierra el flujo. Este es el modo más eficiente para los archivos, porque limita los accesos al disco. No es adecuado para todos los flujos, en particular los flujos de red: en un diálogo entre dos interlocutores, lo que uno escribe debe ser leído de inmediato por el otro, y el flujo de escritura debe estar configurado con [AutoFlush=true] (modo de vaciado automático)
[public string NewLine { get; set; }]
el carácter de fin de línea escrito por [WriteLine]. Por defecto, es el carácter de fin de línea del sistema: "\r\n" en Windows, "\n" en Linux y macOS
[public Encoding Encoding { get; }]
la codificación utilizada

Métodos:

Método
función
[public void Dispose()]
Cierra el flujo después de escribir el contenido del búfer en el archivo. Debe ejecutarse después de procesar el flujo; [Close] realiza la misma acción
[public void Flush()]
escribe el contenido del búfer en el archivo sin esperar a que esté lleno
[public void Write(T value)]
escribe [value] en el archivo asociado al flujo. Aquí, [T] no es un tipo genérico, sino que simboliza el hecho de que el método [Write] acepta distintos tipos de parámetros ([string], [int], [object]…)
[public void WriteLine(T value)]
Igual que [Write] pero agregando la marca de fin de línea ([NewLine])

El programa [files-02.cs] es el siguiente:

// escritura de un archivo de texto con StreamWriter
const string fileName = "infos2.txt";
try
{
    // creación del archivo de texto (si ya existe, se sobrescribe)
    using (var stream = new StreamWriter(fileName))
    {
        Console.WriteLine($"AutoFlush mode: {stream.AutoFlush}, encoding: {stream.Encoding.WebName}");
        // bucle mientras la línea escrita no esté vacía
        while (true)
        {
            Console.Write("line (nothing to stop): ");
            string line = (Console.ReadLine() ?? "").Trim();
            if (line == "")
            {
                break;
            }
            // escritura de la línea en el archivo de texto
            stream.WriteLine(line);
        }
    } // cierre del flujo: el búfer se escribe en el archivo

    // verificación: volvemos a leer el archivo creado
    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

Comentarios:

  • línea 6: una vez más, usamos la instrucción [using] para no tener que cerrar explícitamente el flujo. Este cierre se produce automáticamente al final del bloque (llave de cierre de la línea 21). Es este cierre el que escribe en el archivo el texto restante en el búfer; sin él, el archivo podría quedar incompleto;
  • línea 19: escribe una línea en el archivo de texto;
  • línea 24: la clase [FileInfo] proporciona información sobre un archivo, en este caso su tamaño en bytes. Los 18 bytes se desglosan así: 16 caracteres, más dos saltos de línea de un byte ("\n" en Linux, donde se ejecutó el código; en Windows, cada salto de línea "\r\n" ocuparía 2 bytes);
  • línea 28: ¿por qué un [try / catch]? Podríamos especificar un nombre de archivo de la forma [dir1/dir2/file] con un directorio [dir1/dir2] que no existe, lo que haría imposible crear el archivo. Se lanzaría entonces una excepción [DirectoryNotFoundException], derivada de [IOException]. Hay otros casos de excepción posibles (disco lleno, permisos insuficientes, etc.).

5.6.3. Las clases File, Path y Directory

Para las operaciones comunes, la clase estática [File] elimina la necesidad de manejar flujos: un único método abre el archivo, lo lee o lo escribe por completo y luego lo cierra. Las clases estáticas [Path] y [Directory] gestionan las rutas y los directorios, respectivamente.

método
función
[File.ReadAllText(path)]
devuelve el contenido del archivo como una cadena
[File.ReadAllLines(path)]
Devuelve las líneas del archivo en un arreglo [string[]]
[File.ReadLines(path)]
devuelve las líneas del archivo como una secuencia [IEnumerable<string>] leída bajo demanda
[File.WriteAllText(path, contents)]
crea (o sobrescribe) el archivo y escribe en él [contents]; [WriteAllLines] escribe una colección de líneas
[File.AppendAllText(path, contents)], [File.AppendAllLines(path, lines)]
agrega texto —líneas— al final del archivo (que se crea si no existe)
[File.ReadAllBytes(path)], [File.WriteAllBytes(path, bytes)]
lee y escribe el archivo como un arreglo de bytes
[File.Exists(path)], [File.Delete(path)], [File.Copy(source, dest)], [File.Move(source, dest)]
comprueba si un archivo existe, lo elimina, lo copia o lo mueve
[Path.Combine(p1, p2, ...)]
construye una ruta a partir de sus elementos, usando el separador del sistema
[Path.GetFileName(path)], [Path.GetExtension(path)], [Path.GetDirectoryName(path)]
extrae el nombre de archivo, la extensión y la carpeta de una ruta
[Directory.CreateDirectory(path)]
crea la carpeta y sus carpetas superiores si no existen
[Directory.GetFiles(path, pattern)], [Directory.EnumerateFiles(path, pattern)]
archivos de la carpeta cuyos nombres coinciden con el patrón ([*.txt]…), en un arreglo o en una secuencia
[Directory.Exists(path)], [Directory.Delete(path, recursive)]
comprueba si existe una carpeta y la elimina (junto con su contenido si [recursive] es igual a [true])

El programa [files-03.cs] los utiliza:

using System.Text;

// las clases estáticas File, Path y Directory

// Path.Combine construye una ruta con el separador del sistema (\ en Windows, / en 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 crea la carpeta (y sus padres) si no existe
Directory.CreateDirectory(folder);

// File.WriteAllText: crea (o sobrescribe) un archivo con el texto dado, en UTF-8 sin BOM
File.WriteAllText(path, "Angers\nNantes\n");
// File.AppendAllLines: agrega líneas al final del archivo
File.AppendAllLines(path, ["Paris", "Lyon"]);
// File.ReadAllLines: todas las líneas en un arreglo
string[] lines = File.ReadAllLines(path);
Console.WriteLine($"ReadAllLines : {lines.Length} lines [{string.Join(", ", lines)}]");
// File.ReadAllText: todo el archivo en una cadena
Console.WriteLine($"ReadAllText : {File.ReadAllText(path).Length} characters");
// File.ReadLines: las líneas se leen una por una, bajo demanda (IEnumerable<string>)
foreach (string city in File.ReadLines(path).Where(l => l.StartsWith('N') || l.StartsWith('L')))
{
    Console.WriteLine($"ReadLines + Where : {city}");
}

// la codificación: UTF-8 sin BOM por defecto; se puede imponer otra
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)}");
}
// un archivo Latin-1 leído de nuevo como UTF-8: se pierden los caracteres acentuados
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");
}

// limpieza: eliminación de la carpeta y de su contenido
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

Comentarios:

  • Línea 7: [Path.Combine] usa el separador de rutas del sistema. Los ejercicios del curso se ejecutaron en Linux: la ruta resultante es [data/cities.txt]; en Windows, sería [data\cities.txt]. Construir las rutas con [Path.Combine] en lugar de concatenar cadenas hace que el código sea portable;
  • línea 11: crear la carpeta [data] no provoca un error si ya existe;
  • Líneas 14–18: escritura, adición y lectura, cada una en una sola instrucción;
  • línea 23: [File.ReadLines] devuelve una secuencia: las líneas se leen una por una a medida que avanza el bucle, como los elementos de un iterador. Se le puede aplicar LINQ y, por lo tanto, procesar un archivo de varios gigabytes sin cargarlo en memoria, que es lo que haría [ReadAllLines] . El archivo se cierra al final de la iteración;
  • líneas 29–36: el mismo texto “café” se escribe con tres codificaciones, y luego los bytes de los archivos se muestran en hexadecimal:
    • En UTF-8, la codificación predeterminada de .NET, los caracteres acentuados ocupan 2 bytes (é = C3 A9) y los demás 1 byte: 5 bytes para 4 caracteres;
    • en UTF-8 con BOM (Byte Order Mark), el archivo comienza con los 3 bytes EF BB BF, que indican al software que el archivo está codificado en UTF-8. [new UTF8Encoding(true)] indica al sistema que escriba este BOM;
    • en Latin-1 (ISO-8859-1), la codificación tradicional de los textos de Europa occidental, cada carácter ocupa un byte (é = E9);
  • Línea 39: leer un archivo con una codificación distinta de la utilizada para escribirlo altera los caracteres acentuados: el byte E9, al final del archivo, no es válido en UTF-8, y cada byte inválido se reemplaza por el carácter �. Al leer, [File.ReadAllText] y [StreamReader] reconocen el BOM si está presente; de lo contrario, suponen UTF-8, a menos que se especifique otra codificación (línea 40). Hoy la regla es simple: los archivos de texto se escriben y se leen en UTF-8;
  • línea 44: los nombres de los archivos de texto de la carpeta. [GetFiles] no garantiza el orden de los nombres; el método de LINQ [Order] (.NET 7) los ordena;
  • línea 50: elimina la carpeta y su contenido. El parámetro se pasa por nombre, [recursive: true], lo que hace la llamada más legible que un simple [true] (argumentos con nombre, capítulo 3).

Todos estos métodos tienen versiones asíncronas ([File.ReadAllTextAsync], [File.ReadAllLinesAsync]…): las usaremos en el capítulo 9, dedicado a la programación asíncrona.

5.7. Archivos binarios

5.7.1. Las clases BinaryWriter y BinaryReader

Las clases [System.IO.BinaryWriter] y [System.IO.BinaryReader] se utilizan para escribir y leer archivos binarios. En un archivo de este tipo, los datos no se escriben como texto sino en su forma interna: un [int] siempre ocupa 4 bytes, sea cual sea su valor.

Consideremos la siguiente aplicación:

1
2
3
4
// sintaxis: dotnet run files-04.cs -- text binary logs
// leemos un archivo de texto (text) y almacenamos su contenido en un archivo binario (binary)
// el archivo de texto tiene líneas de la forma name : age que escribimos en la forma (string, int)
// (logs) es un archivo de registro de texto

El archivo de texto [persons1.txt] tiene el siguiente contenido:

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

jacques : 11
sylvain : 12
xx : -1

xx: yy : zz
xx : yy

El programa [files-04.cs] es el siguiente:

// sintaxis: dotnet run files-04.cs -- text binary logs
// leemos un archivo de texto (text) y almacenamos su contenido en un archivo binario (binary)
// el archivo de texto tiene líneas de la forma name : age que escribimos en la forma (string, int)
// (logs) es un archivo de registro de texto

// se necesitan 3 argumentos
if (args.Length != 3)
{
    Console.WriteLine("syntax: dotnet run files-04.cs -- text binary logs");
    return 1;
}
try
{
    // apertura del archivo de texto para lectura
    using var input = new StreamReader(args[0]);
    // apertura del archivo binario para escritura
    using var output = new BinaryWriter(new FileStream(args[1], FileMode.Create, FileAccess.Write));
    // apertura del archivo de registro para escritura
    using var logs = new StreamWriter(args[2]);
    // procesamiento del archivo de texto
    string? line;
    int lineNumber = 0, nbPersons = 0;
    while ((line = input.ReadLine()) != null)
    {
        // una línea más
        lineNumber++;
        // ¿línea vacía? la ignoramos
        if (line.Trim() == "")
        {
            continue;
        }
        // una línea name : age
        string[] fields = line.Split(':', StringSplitOptions.TrimEntries);
        // se necesitan 2 campos
        if (fields.Length != 2)
        {
            logs.WriteLine($"Line no. [{lineNumber}] of the file [{args[0]}] has an incorrect number of fields");
            continue;
        }
        // el 1.er campo no debe estar vacío
        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;
        }
        // el segundo campo debe ser un entero >= 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;
        }
        // si no hay error, escribimos los datos en el archivo binario
        if (!error)
        {
            output.Write(name);
            output.Write(age);
            nbPersons++;
        }
    }
    Console.WriteLine($"{lineNumber} lines read, {nbPersons} persons written to [{args[1]}], errors in [{args[2]}]");
    // fin del bloque try: los tres flujos se cierran aquí, en el orden inverso al de su apertura
}
catch (FileNotFoundException e)
{
    // e.FileName es la ruta completa del archivo; solo mostramos su nombre
    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;

Veamos con más detalle las operaciones que involucran la clase [BinaryWriter]:

  • Línea 17: el objeto [BinaryWriter] se abre mediante la operación [new BinaryWriter(new FileStream(args[1], FileMode.Create, FileAccess.Write))]. El argumento del constructor debe ser un flujo ([Stream]). Aquí es un flujo creado a partir de un archivo ([FileStream]), para el cual se especifica:
    • el nombre;
    • la operación que se realizará, en este caso [FileMode.Create] para crear el archivo (o sobrescribirlo si existe);
    • el tipo de acceso, en este caso [FileAccess.Write] para acceso de escritura al archivo;
  • líneas 57–58: las operaciones de escritura. La clase [BinaryWriter] tiene métodos [Write] sobrecargados para escribir los distintos tipos de datos simples ([int], [double], [decimal], [bool], [string]...);
  • líneas 15–19: los tres flujos se abren con declaraciones [using]. Se cerrarán al final del bloque [try], en el orden inverso al de su apertura. El curso de 2008 los cerraba en una cláusula [finally] después de comprobar que no fueran [null]: la declaración [using] hace lo mismo en una sola línea;
  • línea 10: las instrucciones de nivel superior pueden terminar con un [return n]; n es entonces el código de salida del programa, que un script puede comprobar (0: éxito);
  • línea 33: la opción [TrimEntries] elimina los espacios alrededor del nombre y de la edad;
  • línea 49: la edad debe ser un entero positivo o cero. Gracias al comportamiento de cortocircuito del operador [||], la condición [age < 0] solo se evalúa si la conversión tuvo éxito.

Los tres argumentos del programa se pasan después de [--] en el [dotnet run] comando. Los resultados son los siguientes:

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

El archivo de registro [logs.txt] contiene lo siguiente:

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]

El contenido del archivo binario [persons1.bin] puede mostrarse en hexadecimal con el comando de Linux [od] (en Windows, el comando de PowerShell [Format-Hex] produce una visualización similar):

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

Esto muestra cómo [BinaryWriter] escribe los datos:

  • una cadena se escribe precedida de su longitud en bytes: el byte 04 seguido de los 4 bytes de “paul” (70 61 75 6c);
  • un entero [int] se escribe en 4 bytes, con el byte menos significativo primero: 10 se escribe como 0a 00 00 00;
  • los datos se escriben uno tras otro, sin separadores ni saltos de línea: el archivo mide 44 bytes (línea 5: con la opción [-A d], [od] muestra las posiciones en decimal).

Para leer este archivo, por lo tanto, hay que conocer el orden y el tipo exactos de los datos que se escribieron. Esto es lo que hace el programa [files-05.cs]; realiza la operación inversa: lee el archivo binario para crear un archivo de texto. Si el archivo de texto resultante contiene los datos correctos del archivo original, sabremos que la conversión texto → binario → texto fue exitosa.

// sintaxis: dotnet run files-05.cs -- binary text
// leemos un archivo binario (binary) y almacenamos su contenido en un archivo de texto (text)
// el archivo binario contiene pares (string, int)
// el archivo de texto tendrá líneas de la forma name:age

// se necesitan 2 argumentos
if (args.Length != 2)
{
    Console.WriteLine("syntax: dotnet run files-05.cs -- binary text");
    return 1;
}
try
{
    // apertura del archivo binario para lectura
    using var input = new BinaryReader(new FileStream(args[0], FileMode.Open, FileAccess.Read));
    // apertura del archivo de texto para escritura
    using var output = new StreamWriter(args[1]);
    // procesamiento del archivo binario, mientras no estemos al final del flujo
    int nbPersons = 0;
    while (input.BaseStream.Position < input.BaseStream.Length)
    {
        // lectura de name y luego de age: en el orden en que se escribieron
        string name = input.ReadString();
        int age = input.ReadInt32();
        // escritura en el archivo de texto
        output.WriteLine($"{name}:{age}");
        nbPersons++;
    }
    Console.WriteLine($"{nbPersons} persons read from [{args[0]}] and written to [{args[1]}]");
}
catch (EndOfStreamException)
{
    // el archivo termina en medio de un registro
    Console.WriteLine($"The file [{args[0]}] is truncated");
    return 2;
}
catch (FileNotFoundException e)
{
    // e.FileName es la ruta completa del archivo; solo mostramos su nombre
    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;

Veamos con más detalle las operaciones con la clase [BinaryReader]:

  • línea 15: el objeto [BinaryReader] se abre sobre un flujo [FileStream] con el modo [FileMode.Open] (para abrir un archivo existente) y el modo de acceso [FileAccess.Read] (acceso de solo lectura);
  • líneas 23–24: operaciones de lectura. La clase [BinaryReader] ofrece los métodos [ReadXX] para leer distintos tipos de datos simples: [ReadString], [ReadInt32], [ReadDouble], [ReadDecimal], [ReadBoolean]... Deben llamarse en el mismo orden en que se escribió;
  • línea 20: la propiedad [BaseStream] proporciona el flujo subyacente, en este caso [FileStream]. La lectura continúa hasta que la posición actual en el archivo alcanza el final del archivo. La versión de 2008 leía indefinidamente y detectaba el final del archivo mediante la excepción [EndOfStreamException]: una excepción debe seguir siendo excepcional, y el final de un archivo no lo es;
  • línea 31: esta excepción ahora señala una anomalía real: un archivo que termina en medio de un registro.

Ejecutemos el programa con el archivo [persons1.bin] generado anteriormente:

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

El contenido de [persons2.txt] es el siguiente:

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

Encontramos las 4 personas válidas del archivo [persons1.txt]. Con un archivo [truncated.bin] formado por los primeros 30 bytes de [persons1.bin], la lectura de la edad de Jacques falla:

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

5.7.2. La serialización JSON

Escribir y leer un archivo binario byte por byte es tedioso, y la más mínima discrepancia entre la escritura y la lectura produce resultados incorrectos. Por lo general es preferible serializar los objetos: convertirlos automáticamente en una secuencia de bytes o de caracteres y luego deserializarlos para reconstruirlos.

.NET proporcionaba para ello la clase [BinaryFormatter], que serializaba los objetos en un formato binario específico de .NET. Ahora ha sido eliminada: se declaró obsoleta en .NET 5 y su implementación se eliminó en .NET 9, porque deserializar datos de una fuente no confiable con [BinaryFormatter] permitía ejecutar código arbitrario. Microsoft recomienda reemplazarla por la serialización JSON de la biblioteca [System.Text.Json], integrada en .NET desde .NET Core 3.0.

JSON (JavaScript Object Notation) es un formato basado en texto, legible por humanos y universal: es el formato de intercambio de los servicios web (capítulo 13) y de numerosos archivos de configuración. Un objeto se escribe entre llaves con pares "propiedad":valor, y las matrices se encierran entre corchetes.

La clase estática [System.Text.Json.JsonSerializer] tiene dos métodos principales:

método
función
[string Serialize<T>(T value, JsonSerializerOptions? options = null)]
devuelve el texto JSON que representa el objeto [value]
[T? Deserialize<T>(string json, JsonSerializerOptions? options = null)]
reconstruye un objeto de tipo [T] a partir del texto JSON [json]; lanza una [JsonException] si el texto es incorrecto

El programa [files-06.cs] los utiliza:

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

// serialización JSON con System.Text.Json

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

// 1 - serialización predeterminada: una sola línea, caracteres no ASCII escapados
string json = JsonSerializer.Serialize(persons[1]);
Console.WriteLine($"[default] {json}");

// 2 - opciones: sangría, caracteres acentuados dejados tal cual
var options = new JsonSerializerOptions
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.Create(UnicodeRanges.All)
};
json = JsonSerializer.Serialize(persons, options);
// escritura en un archivo de texto
File.WriteAllText("persons.json", json);
Console.WriteLine("[persons.json]");
Console.WriteLine(File.ReadAllText("persons.json"));

// 3 - deserialización: de texto JSON a 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 - sin atributos: las opciones "Web" ponen los nombres de propiedades en camelCase
var web = new JsonSerializerOptions(JsonSerializerDefaults.Web);
string jsonArticle = JsonSerializer.Serialize(new Article("A12", 12.5m), web);
Console.WriteLine($"[Web options] {jsonArticle}");
// y no distinguen mayúsculas y minúsculas al leer
Article? article = JsonSerializer.Deserialize<Article>("""{ "CODE": "B7", "price": 3 }""", web);
Console.WriteLine($"[Web options] {article}");

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

// una persona; los atributos [JsonPropertyName] fijan los nombres de las propiedades JSON
record Person(
    [property: JsonPropertyName("name")] string Name,
    [property: JsonPropertyName("age")] int Age,
    [property: JsonPropertyName("hobbies")] List<string> Hobbies);

// un artículo, sin 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.

Comentarios:

  • Línea 1: una directiva para aplicaciones de un solo archivo. De forma predeterminada, estas se configuran para la compilación nativa (AOT, "ahead of time"), que produce un ejecutable independiente pero deshabilita los mecanismos que dependen del descubrimiento de tipos en tiempo de ejecución (reflexión). Sin embargo, [JsonSerializer] usa reflexión de forma predeterminada para descubrir las propiedades de los objetos que se van a serializar: sin esta directiva, la compilación produce advertencias y la ejecución falla. Un proyecto [.csproj] estándar, como el de la aplicación de ejemplo, no tiene esta restricción. Para una aplicación compilada de forma nativa, [System.Text.Json] ofrece un generador de código fuente (una clase derivada de [JsonSerializerContext]) que genera el código de serialización en tiempo de compilación: no lo trataremos aquí;
  • líneas 60–63: el registro [Person] que se va a serializar. Sus propiedades llevan el atributo [JsonPropertyName], que establece el nombre de la propiedad en el texto JSON como [name] en lugar de [Name]. En un registro posicional, [property: ...] indica que el atributo se aplica a la propiedad generada y no al parámetro del constructor;
  • línea 17: serialización de un objeto con las opciones predeterminadas: el texto se escribe en una sola línea y los caracteres no ASCII se escapan: [é] se convierte en [é]. El texto sigue siendo correcto, pero es difícil de leer;
  • líneas 21–26: la opción [WriteIndented] produce texto con sangría en varias líneas; la opción [Encoder] especifica qué caracteres se dejan tal cual (en este caso, todos los caracteres Unicode). Una lista se serializa como una matriz JSON;
  • línea 28: el texto JSON se guarda en un archivo de texto: así es como hoy se reemplaza la serialización binaria;
  • línea 34: la deserialización reconstruye la lista. [Deserialize] crea los objetos [Person] llamando al constructor del registro, cuyos parámetros se asocian con las propiedades JSON del mismo nombre. El resultado es de tipo [List<Person>?]: el texto JSON [null] es un documento válido que produce [null];
  • línea 42: las opciones “Web” (que los servicios web de ASP.NET Core usan de forma predeterminada) escriben los nombres de las propiedades en formato camelCase (primera letra en minúscula): [Code] se convierte en [code], sin necesidad de un atributo. Al analizar, no distinguen mayúsculas de minúsculas: [CODE] se acepta (línea 31);
  • línea 52: un documento JSON no válido (en este caso, una cadena donde se espera un número) provoca una excepción [JsonException], cuyo mensaje indica la ubicación del error.

Usaremos JSON en la siguiente aplicación de ejemplo y a lo largo del curso.

5.8. Expresiones regulares

La clase [System.Text.RegularExpressions.Regex] permite el uso de expresiones regulares. Estas permiten validar el formato de una cadena. Por ejemplo, se puede verificar que una cadena que representa una fecha tenga efectivamente el formato dd/mm/aa. Para ello, se usa un patrón y se compara la cadena con ese patrón. En este ejemplo, d, m y a deben ser dígitos. El patrón de un formato de fecha válido es, por lo tanto, [\d\d/\d\d/\d\d], donde el símbolo [\d] representa un dígito. Los símbolos que se pueden usar en un patrón son los siguientes:

carácter
descripción
[\]
marca el carácter siguiente como carácter especial o literal. Por ejemplo, [n] corresponde al carácter n, [\n] corresponde a un carácter de nueva línea, [\\] corresponde a \ y [\(] corresponde a (
[^]
corresponde al inicio de la cadena
[$]
corresponde al final de la cadena
[*]
coincide con el elemento anterior cero o más veces. Así, [zo*] coincide con z o zoo
[+]
coincide con el elemento anterior una o más veces. Así, [zo+] coincide con "zoo", pero no con "z"
[?]
coincide con el elemento anterior cero o una vez. Por ejemplo, [a?ve?] coincide con “ve” en “lever”
[.]
coincide con cualquier carácter individual, excepto el carácter de nueva línea
[(pattern)]
busca el patrón y almacena la coincidencia (un grupo). La subcadena coincidente se puede extraer de la colección [Groups] del resultado. Para buscar coincidencias con caracteres entre paréntesis, use [\(] o [\)]
[x|y]
coincide con x o con y. Por ejemplo, [z|foot] coincide con z o foot; [(z|f)oo] coincide con zoo o foo
[{n}]
n es un entero no negativo. Coincide exactamente n veces con el elemento anterior. Por ejemplo, [o{2}] no coincide con la o de Bob, pero sí con las dos primeras o de fooooot
[{n,}]
coincide con el elemento anterior al menos n veces. Por ejemplo, [o{2,}] no coincide con la 'o' de 'Bob', pero sí con todas las 'o' de 'fooooot'. [o{1,}] equivale a [o+], y [o{0,}] equivale a [o*]
[{n,m}]
coincide con el elemento anterior al menos n veces y como máximo m veces. Por ejemplo, [o{1,3}] coincide con las tres primeras “o” de “foooooot”; [o{0,1}] equivale a [o?]
[xyz]
conjunto de caracteres: coincide con uno de los caracteres especificados. Por ejemplo, [abc] coincide con la letra “a” en “plat”
[^xyz]
conjunto negativo de caracteres: coincide con cualquier carácter que no esté en la lista. Por ejemplo, [^abc] coincide con "p" en "plat"
[a-z]
rango de caracteres: coincide con cualquier carácter del rango especificado, en este caso una letra minúscula sin acento
[^m-z]
rango negativo de caracteres: coincide con cualquier carácter que no esté entre 'm' y 'z'
[\b]
coincide con un límite de palabra, es decir, la posición entre un carácter de palabra y un carácter que no es de palabra. Por ejemplo, [er\b] coincide con "er" en "lever", pero no con "er" en "verb"
[\B]
corresponde a una posición que no es un límite de palabra. [en*t\B] corresponde a “ent” en “entertain”
[\d]
corresponde a un dígito; equivale a [0-9] (en .NET, también para los dígitos de otros alfabetos Unicode)
[\D]
corresponde a un carácter que no es un dígito
[\f], [\n], [\r], [\t], [\v]
corresponden, respectivamente, a los caracteres de salto de página, nueva línea, retorno de carro, tabulación y tabulación vertical
[\s]
corresponde a cualquier espacio en blanco: espacio, tabulación, salto de página, salto de línea… Equivale a [ \f\n\r\t\v], más otros caracteres de espacio en blanco de Unicode (espacio de no separación, etc.)
[\S]
coincide con cualquier carácter que no sea un espacio en blanco
[\w]
coincide con cualquier carácter de palabra: letra (con o sin acentos), dígito o guion bajo
[\W]
coincide con cualquier carácter que no sea un carácter de palabra
[\num]
num es un entero positivo: hace referencia al grupo número num. Por ejemplo, [(.)\1] coincide con dos caracteres idénticos consecutivos
[\xnn], [\unnnn]
corresponde al carácter hexadecimal nn (2 dígitos) o nnnn (4 dígitos). Por ejemplo, [\x41] corresponde a A

Un elemento de un patrón puede aparecer una o varias veces. Veamos algunos ejemplos con el símbolo [\d], que representa un solo dígito:

patrón
Significado
[\d]
un dígito
[\d?]
0 o 1 dígito
[\d*]
0 o más dígitos
[\d+]
1 o más dígitos
[\d{2}]
2 dígitos
[\d{3,}]
Al menos 3 dígitos
[\d{5,7}]
entre 5 y 7 dígitos

Imaginemos ahora un modelo capaz de describir el formato esperado de una cadena:

cadena objetivo
patrón
una fecha en formato dd/mm/aa
[\d{2}/\d{2}/\d{2}]
una hora en formato hh:mm:ss
[\d{2}:\d{2}:\d{2}]
un entero sin signo
[\d+]
una secuencia de espacios, que puede estar vacía
[\s*]
un entero sin signo que puede estar precedido o seguido de espacios
[\s*\d+\s*]
un entero que puede tener signo y estar precedido o seguido de espacios
[\s*[+-]?\s*\d+\s*]
un número real sin signo que puede estar precedido o seguido de espacios
[\s*\d+(\.\d*)?\s*]
un número real que puede tener signo y estar precedido o seguido de espacios
[\s*[+-]?\s*\d+(\.\d*)?\s*]
una cadena que contiene la palabra "just"
[\bjust\b]

El curso de 2008 usaba [+|-] para el signo: entre corchetes, el carácter [|] no tiene ningún significado especial, y este formato también aceptaba el signo | antes de un número. También usaba [(.\d*)] para la parte decimal: el punto sin escapar representa allí cualquier carácter. Los patrones anteriores han sido corregidos.

Se puede especificar en qué parte de la cadena se busca el patrón:

patrón
significado
[^pattern]
el patrón está al inicio de la cadena
[pattern$]
El patrón está al final de la cadena
[^pattern$]
El patrón está al inicio y al final de la cadena
[pattern]
El patrón se busca en cualquier parte de la cadena, comenzando desde el inicio de la cadena
cadena de búsqueda
patrón
una cadena que termina con un signo de exclamación
[!$]
una cadena que termina con un punto
[\.$]
una cadena que comienza con la secuencia //
[^//]
una cadena formada por una sola palabra, posiblemente precedida o seguida de espacios
[^\s*\w+\s*$]
una cadena formada por exactamente dos palabras, posiblemente precedidas o seguidas de espacios
[^\s*\w+\s+\w+\s*$]
una cadena que contiene la palabra "secret"
[\bsecret\b]

Se pueden “extraer” subconjuntos de un patrón. Así, no solo podemos verificar que una cadena coincide con un patrón determinado, sino también extraer de esa cadena los elementos que corresponden a los subconjuntos del patrón que se han encerrado entre paréntesis. Por ejemplo, si se analiza una cadena que contiene una fecha en formato dd/mm/aa y se quieren extraer también los componentes dd, mm y aa de esa fecha, se usaría el patrón [(\d\d)/(\d\d)/(\d\d)].

En el código C#, un patrón se escribe de preferencia como una cadena textual [@"..."]: de esta manera, no es necesario duplicar los numerosos caracteres [\] de los patrones. Con una cadena normal, habría que escribir ***["\\\\d+"] en lugar de ***[@"\\d+"].

5.8.1. Verificar si una cadena coincide con un patrón dado

Un objeto de tipo [Regex] se construye de la siguiente manera:

constructor
función
[public Regex(string pattern)]
crea un objeto de “expresión regular” a partir de un patrón pasado como parámetro ([pattern]). Se lanza una excepción [ArgumentException] si el patrón es incorrecto
[public Regex(string pattern, RegexOptions options, TimeSpan matchTimeout)]
igual que el anterior, con opciones y un tiempo de espera (véase más adelante)

Una vez construida la expresión regular, se puede comparar con cadenas de caracteres mediante el método [IsMatch]:

método
función
[public bool IsMatch(string input)]
true si la cadena [input] contiene una subcadena que coincide con el patrón de la expresión regular

El programa [regex-01.cs] es el siguiente:

using System.Text.RegularExpressions;

// verificación de que una cadena coincide con un patrón
string pattern1 = @"^\s*\d+\s*$";
var regex1 = new Regex(pattern1);
// comparación de muestras con el patrón
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}]");
    }
}
// el método estático Regex.IsMatch evita crear uno mismo el 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

Comentarios:

  • línea 4: el patrón de un entero sin signo, opcionalmente rodeado de espacios, que ocupa toda la cadena (anclas [^] y [$]);
  • línea 9: la cadena “123a”, rodeada de espacios, no coincide con el patrón: el carácter “a” no puede ser un dígito ni un espacio. Sin las anclas [^] y [$], la cadena coincidiría, ya que contiene un número;
  • línea 19: la clase [Regex] también tiene métodos estáticos que reciben el patrón como parámetro. .NET almacena en memoria los patrones usados más recientemente: se pueden utilizar en un bucle sin preocuparse de que el patrón se analice en cada llamada.

5.8.2. Encontrar todas las ocurrencias de un patrón en una cadena

El método [Matches] recupera los elementos de una cadena que coinciden con un patrón:

método
función
[public MatchCollection Matches(string input)]
devuelve la colección de elementos de la cadena [input] que coinciden con el patrón

La clase [MatchCollection] tiene una propiedad, [Count], que es el número de elementos de la colección. Si [results] es un objeto [MatchCollection], entonces [results[i]] es el i-ésimo elemento de esa colección; es de tipo [Match]. La clase [Match] tiene varias propiedades, entre ellas las siguientes:

  • [Value]: el valor del objeto [Match], es decir, un elemento que coincide con el patrón;
  • [Index]: la posición en la que se encontró el elemento en la cadena explorada.

El programa [regex-02.cs] es el siguiente:

using System.Text.RegularExpressions;

// búsqueda de todas las ocurrencias de un patrón en una cadena
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}");
}
// una MatchCollection es una secuencia: LINQ se le puede aplicar
int sum = results.Sum(m => int.Parse(m.Value));
Console.WriteLine($"sum of the numbers found: {sum}");
// Count cuenta las ocurrencias sin construir la colección
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

Comentarios:

  • Línea 4: el patrón buscado es una secuencia de dígitos;
  • línea 6: la cadena en la que se busca este patrón;
  • línea 7: se recuperan todos los elementos de [sample3] que coinciden con el patrón [pattern2] ;
  • líneas 10–12: se muestran. Una [MatchCollection] se recorre con [foreach], como una lista;
  • línea 15: [MatchCollection] implementa [IEnumerable<Match>]: se le aplica LINQ. Aquí, sumamos los números encontrados;
  • línea 18: el método [Count] (.NET 7) cuenta las ocurrencias del patrón sin construir una colección. El patrón [aeiouy] denota una vocal.

5.8.3. Recuperación de partes de un patrón

Como se mencionó antes, las partes de un patrón encerradas entre paréntesis se almacenan: son los grupos. El programa [regex-03.cs] los utiliza:

using System.Text.RegularExpressions;

// recuperación de partes de un patrón: los grupos
string pattern3 = @"(\d\d):(\d\d):(\d\d)";
var regex3 = new Regex(pattern3);
string sample4 = "It is 18:05:49";
// Match devuelve la primera ocurrencia del patrón
Match result = regex3.Match(sample4);
if (result.Success)
{
    Console.WriteLine($"The sample [{sample4}] matches the pattern [{pattern3}]");
    // mostramos los grupos entre paréntesis
    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 con nombre: (?<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))
{
    // un grupo se designa por su nombre y no por su 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: los grupos pueden reutilizarse en la cadena de reemplazo
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.

Comentarios:

  • Línea 8: la cadena [sample4] se compara con el patrón [regex3] mediante el método [Match]. Este método devuelve la primera ocurrencia del patrón como un objeto [Match], que ya se presentó. Aquí usamos dos propiedades nuevas de esta clase:
    • [Success] (línea 9): indica si se encontró una coincidencia;
    • [Groups] (línea 13): una colección donde [Groups[0]] corresponde a la parte de la cadena que representa el patrón, y [Groups[i]] (i >= 1) corresponde al i-ésimo par de paréntesis;
  • si [result] es de tipo [Match], entonces [result.Groups] es de tipo [GroupCollection] y [result.Groups[i]] es de tipo [Group]. La clase [Group] tiene, al igual que la clase [Match], las propiedades [Value] (el texto capturado por el grupo) e [Index] (su posición en la cadena analizada);
  • línea 24: un grupo puede nombrarse con la sintaxis [(?<name>...)]. Aquí, el patrón reconoce una fecha en formato d/m/aaaa, con día y mes de uno o dos dígitos;
  • líneas 29–31: un grupo con nombre se referencia por su nombre en lugar de por su número: el código es más legible y no depende del orden de los paréntesis;
  • línea 32: el tipo [DateOnly] (.NET 6) representa una fecha sin hora. Se muestra en el formato [dddd d MMMM yyyy]: el día de la semana aparece en inglés;
  • línea 37: el método [Replace] reemplaza cada ocurrencia del patrón por una cadena en la que [${name}] (o [$1], [$2]… para los grupos numerados) denota el valor de un grupo. Así, las fechas se reformatean al formato año-mes-día.

5.8.4. Un programa de aprendizaje

Encontrar la expresión regular que verifica si una cadena coincide con cierto patrón puede ser a veces un verdadero desafío. El programa [regex-04.cs] permite practicar. Recibe como entrada un patrón y una cadena e indica si la cadena coincide o no con el patrón.

using System.Text.RegularExpressions;

// un programa para aprender expresiones regulares
while (true)
{
    // pedimos el patrón
    Console.Write("Type the pattern to test or nothing to stop: ");
    string pattern = Console.ReadLine() ?? "";
    // ¿terminó?
    if (pattern.Trim() == "")
    {
        break;
    }
    // creamos la expresión regular; un patrón incorrecto provoca una excepción
    Regex regex;
    try
    {
        regex = new Regex(pattern, RegexOptions.None, TimeSpan.FromSeconds(1));
    }
    catch (ArgumentException e)
    {
        Console.WriteLine($"Error: {e.Message}");
        continue;
    }
    // pedimos las muestras que se compararán con el patrón
    while (true)
    {
        Console.Write($"Type the string to compare with the pattern [{pattern}] or nothing to stop: ");
        string input = Console.ReadLine() ?? "";
        // ¿terminó?
        if (input.Trim() == "")
        {
            break;
        }
        try
        {
            // hacemos la comparación
            MatchCollection results = regex.Matches(input);
            if (results.Count == 0)
            {
                Console.WriteLine("I did not find any matches");
                continue;
            }
            // mostramos los elementos que coinciden con el patrón
            foreach (Match m in results)
            {
                Console.WriteLine($"I found the match [{m.Value}] at position [{m.Index}]");
                // y sus 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");
        }
    }
}

Comentarios:

  • línea 18: la expresión regular se construye con un tiempo de espera de un segundo: si una búsqueda tarda más que eso, se abandona y se lanza una excepción [RegexMatchTimeoutException] (línea 55). Veremos más adelante por qué esto es útil;
  • línea 20: un patrón no válido provoca una excepción [ArgumentException] (más específicamente, [RegexParseException], que deriva de ella);
  • líneas 45–51: para cada coincidencia, se muestran los grupos n.º 1 y siguientes, si los hay.

Este es un ejemplo de la salida:

> 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: 

Los patrones [^\s*\d+\s*$] y [^\s*(\d+)\s*$] demuestran la utilidad de los grupos: el primero reconoce la cadena “1456” precedida de tres espacios, incluidos los espacios; el segundo además extrae el número sin los espacios. El patrón [(a+)+$] se examina más adelante.

5.8.5. El método Split

Ya hemos visto el método [Split] de la clase [String]:

método
función
[public string[] Split(params char[] separator)]
La cadena se trata como una secuencia de campos separados por los caracteres enumerados en la matriz [separator]. El resultado es una matriz con esos campos

El método [Split] de la clase [Regex] permite especificar el separador mediante un patrón:

método
función
[public string[] Split(string input)]
La cadena [input] se divide en campos, separados por un separador que corresponde al patrón del objeto [Regex] actual

Supongamos, por ejemplo, que un archivo de texto contiene líneas de la forma campo1, campo2, ..., campon. Los campos están separados por una coma, pero esta coma puede estar precedida o seguida de espacios. El patrón [\s*,\s*] describe exactamente este separador, como muestra el programa [regex-05.cs]:

using System.Text.RegularExpressions;

// Regex.Split: el separador se define mediante un patrón
string line = "abc  , def  ,ghi ,   jkl";
// una coma precedida y seguida de cualquier cantidad de espacios
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]}]");
}
// varios separadores posibles: ; o | o una secuencia de espacios
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]

Comentarios:

  • línea 6: el separador: una coma precedida y seguida de cualquier cantidad de espacios. Los espacios se eliminan junto con el separador. Observe que la opción [TrimEntries] de [string.Split], presentada anteriormente, permite ahora obtener el mismo resultado sin una expresión regular;
  • línea 13: un separador que puede adoptar varias formas: un punto y coma o una barra vertical ([;|]), o ([|]) una secuencia de espacios ([\s+]). Aquí es necesaria una expresión regular.

5.8.6. Expresiones regulares generadas, opciones, tiempo de espera

Un objeto [Regex] analiza su patrón en tiempo de ejecución y luego lo traduce a una estructura interna que interpreta, o lo compila a código ejecutable si se le pasa la opción [RegexOptions.Compiled]. A partir de .NET 7, el atributo [GeneratedRegex] permite realizar este trabajo en tiempo de compilación: un generador de código fuente escribe el código C# de la búsqueda, que se puede ver en el editor (F12 sobre el método). El patrón se valida en tiempo de compilación, ya no hay costo de análisis al iniciar y el código generado se ejecuta lo más rápido posible. Esta es ahora la forma recomendada de usar un patrón conocido de antemano. El programa [regex-06.cs] es el siguiente:

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

// 1 - expresiones regulares generadas en tiempo de compilación
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 - opciones: aquí IgnoreCase, fijada en el atributo
foreach (string answer in new[] { "yes", "YES", "Yes", "no", "yesss" })
{
    Console.Write($"{answer}={Patterns.Yes().IsMatch(answer)} ");
}
Console.WriteLine();
// las opciones se combinan con |: Multiline hace que ^ y $ coincidan al inicio y al final de cada línea
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 - un tiempo de espera (timeout) protege contra patrones con retroceso (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");
}
// el mismo patrón con el motor sin retroceso responde de inmediato
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}");

// los patrones del programa
static partial class Patterns
{
    // una hora hh:mm:ss con grupos con nombre
    [GeneratedRegex(@"(?<h>\d\d):(?<m>\d\d):(?<s>\d\d)")]
    public static partial Regex Time();

    // sí, sea cual sea la capitalización
    [GeneratedRegex(@"^\s*yes\s*$", RegexOptions.IgnoreCase)]
    public static partial Regex Yes();

    // un patrón patológico, con un tiempo de espera 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

Comentarios:

  • Líneas 39–51: cada patrón se declara mediante un método estático partial ([partial]) sin cuerpo, que genera un [Regex], y va precedido del atributo [GeneratedRegex]. El generador de código fuente escribe el cuerpo del método en otra parte de la clase, que también se declara como [partial]. A partir de C# 13 y .NET 9, también se puede declarar una propiedad parcial: [[GeneratedRegex(...)] private static partial Regex Time { get; }];
  • línea 5: el método se usa como un objeto [Regex] normal;
  • línea 46: el segundo parámetro del atributo es una combinación de opciones [RegexOptions]. [IgnoreCase] ignora las mayúsculas y minúsculas: “YES” y “Yes” coinciden con el patrón;
  • línea 17: las opciones se usan de la misma manera con los métodos de [Regex]. [Multiline] hace coincidir [^] y [$] con el inicio y el final de cada línea de la cadena, en lugar de solo con el inicio y el final de la cadena completa. Otras opciones son útiles: [Singleline] ([.] también coincide con los saltos de línea), [IgnorePatternWhitespace] (los espacios en el patrón se ignoran, lo que permite escribirlo en varias líneas, incluso con comentarios), [ExplicitCapture] (solo se recuerdan los grupos con nombre). Se pueden combinar con el operador [|];
  • línea 50: el patrón [^(a+)+$] es patológico: cuando se aplica a una secuencia de “a” que termina con otro carácter, el motor de expresiones regulares prueba todas las formas posibles de distribuir las “a” entre las repeticiones del grupo antes de concluir que ha fallado. El número de posibilidades se duplica con cada “a” adicional: con 30 “a” hay aproximadamente mil millones de posibilidades. Esto se conoce como retroceso catastrófico. Un patrón así, aplicado a cadenas ingresadas por los usuarios, es una vulnerabilidad de seguridad: bastan unas pocas solicitudes para hacer caer un servidor. El parámetro [matchTimeoutMilliseconds] establece un tiempo de espera de 100 ms: transcurrido este, la búsqueda se abandona con una excepción [RegexMatchTimeoutException] (línea 6);
  • línea 35: la opción [NonBacktracking] (.NET 7) usa un motor distinto, que garantiza un tiempo de búsqueda proporcional a la longitud de la cadena. No admite ciertas construcciones (referencias hacia atrás, como [\1], por ejemplo), pero en este caso devuelve un resultado de inmediato.

Observe que se debe establecer un tiempo de espera o usar [NonBacktracking] siempre que el patrón o la cadena en la que se busca provenga de fuera del programa.

5.9. Aplicación de ejemplo - V3

Retomaremos la aplicación tratada en el capítulo 3 (versión 1) y el capítulo 4 (versión 2). Recuerde que se trata de un ejercicio: la escala de impuestos utilizada es la versión de 2004 (ingresos de 2003), que se ha mantenido sin cambios desde el curso original.

5.9.1. Datos en un archivo

En la versión 2, el cálculo del impuesto se realizaba en la clase abstracta [AbstractTax], que reproducimos aquí sin cambios, salvo por su espacio de nombres:

namespace TaxV3;

public abstract class AbstractTax : ITax
{
    // los tramos del impuesto necesarios para el cálculo provienen de una fuente externa
    // que solo las clases derivadas conocen
    protected abstract TaxBracket[] TaxBrackets { get; }

    // cálculo del impuesto
    public int Calculate(bool married, int nbChildren, int salary)
    {
        // cálculo del número de partes
        decimal shares = (decimal)nbChildren / 2 + (married ? 2 : 1);
        if (nbChildren >= 3)
        {
            shares += 0.5m;
        }
        // cálculo del ingreso gravable y del cociente familiar
        decimal income = 0.72m * salary;
        decimal quotient = income / shares;
        // búsqueda del tramo del impuesto: se usa el último si ningún límite se ajusta
        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 del impuesto
        return (int)(income * bracket.CoeffR - shares * bracket.CoeffN);
    }
}

El método [Calculate] usa los tramos impositivos devueltos por la propiedad abstracta [TaxBrackets] (línea 7). La clase [AbstractTax] no sabe de dónde provienen estos tramos: corresponde a las clases derivadas proporcionarlos. En la versión 2, la clase derivada [HardwiredTax] los incluía directamente en su código. Un tramo impositivo se representa, como en la versión 2, mediante la estructura de tipo registro [TaxBracket]:

1
2
3
4
namespace TaxV3;

// un tramo de la tabla de impuestos
public readonly record struct TaxBracket(decimal Limit, decimal CoeffR, decimal CoeffN);

y el cálculo se describe mediante la interfaz [ITax]:

1
2
3
4
5
6
7
namespace TaxV3;

public interface ITax
{
    // cálculo del impuesto de un contribuyente
    int Calculate(bool married, int nbChildren, int salary);
}

La nueva versión almacena los datos en un archivo, lo que permite modificar la escala de tarifas sin recompilar el programa. Escribimos dos nuevas clases derivadas de [AbstractTax]:

  • [FileTax] lee los tramos de un archivo de texto [TaxData.txt];
  • [JsonTax] los lee de un archivo JSON llamado [TaxData.json].

El archivo de texto [TaxData.txt] contiene un tramo impositivo por línea, con el formato límite: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

El curso de 2008 escribía los números con coma decimal (0,068) y los leía mediante [decimal.TryParse] con la configuración regional de la máquina: el mismo archivo, leído en una máquina británica o estadounidense, habría sido rechazado o, peor aún, mal interpretado. Un archivo de datos no debe depender del idioma de la máquina que lo lee: escribimos los números con punto decimal y los leemos con la referencia cultural invariable ([CultureInfo.InvariantCulture]), que también usan JSON y la mayoría de los formatos de datos.

El archivo [TaxData.json] contiene los mismos datos, en forma de una matriz 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. Errores

El procesamiento de estos archivos puede fallar: archivo inexistente, línea mal formada, número incorrecto, etc. Como en la versión de 2008, creamos una clase de excepción especial para informar de estos errores. El curso de 2008 la llamaba [FileTaxException]; nosotros la llamamos [TaxException], puesto que también se usará para otras fuentes de datos (aquí el archivo JSON y, más adelante, una base de datos). Lleva un código de error:

namespace TaxV3;

// los códigos de error: potencias de 2, que se pueden combinar
[Flags]
public enum ErrorCode
{
    Access = 1,     // no se puede leer el archivo
    Line = 2,       // una línea no tiene tres campos
    Field1 = 4,     // el campo 1 (limit) es incorrecto
    Field2 = 8,     // el campo 2 (coeffR) es incorrecto
    Field3 = 16,    // el campo 3 (coeffN) es incorrecto
    Json = 32       // el documento JSON es incorrecto
}

// la excepción lanzada por las clases que leen los tramos del impuesto
public class TaxException : Exception
{
    // el código de error (una combinación de valores de ErrorCode)
    public int Code { get; init; }

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

Comentarios:

  • líneas 16–22: la clase [TaxException] deriva de la clase [Exception]. Se usará para informar de cualquier error que ocurra durante el procesamiento del archivo de datos. Tiene dos constructores: el primero recibe un mensaje de error y el segundo recibe además la excepción que causó el error, que estará disponible en la propiedad [InnerException];
  • línea 19: la propiedad [Code] almacena el código de error. La palabra clave [init] permite asignarlo solo al crear el objeto, mediante un inicializador de objeto: [new TaxException("...") { Code = 2 }]. Esta es la forma de excepción, con un código entero, que usarán las versiones posteriores de la aplicación;
  • líneas 4–12: una lista de los posibles códigos de error:
    • [Access]: error al acceder al archivo de datos;
    • [Line]: línea que no tiene los tres campos esperados, o archivo que no contiene ningún tramo;
    • [Field1], [Field2], [Field3]: el campo 1, 2 o 3 de una línea es incorrecto;
    • [Json]: el documento JSON es incorrecto.

Algunos de estos errores pueden ocurrir combinados: los tres campos de una línea pueden ser incorrectos. Por ello, la enumeración [ErrorCode] se ha anotado con el atributo [Flags], y sus valores son potencias de 2: cada uno corresponde a un bit del entero. Un error en los campos 2 y 3 dará como resultado el código [Field2 | Field3], que es 8 + 16 = 24. Gracias al atributo [Flags], el método [ToString] de la enumeración muestra tal combinación en la forma “Field2, Field3”.

5.9.3. La clase FileTax

La clase [FileTax] proporciona los tramos leídos de un archivo de texto:

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

namespace TaxV3;

// los tramos del impuesto leídos de un archivo de texto con líneas limit:coeffR:coeffN
public partial class FileTax : AbstractTax
{
    // el separador de campos: el carácter : rodeado de espacios opcionales
    [GeneratedRegex(@"\s*:\s*")]
    private static partial Regex Separator();

    // los tramos del impuesto leídos del archivo
    private readonly TaxBracket[] taxBrackets;

    // implementación de la propiedad abstracta de la clase padre
    protected override TaxBracket[] TaxBrackets => taxBrackets;

    public FileTax(string fileName)
    {
        // el nombre del archivo, sin su ruta, para los mensajes de error
        string name = Path.GetFileName(fileName);
        // los tramos leídos; no conocemos su número de antemano
        List<TaxBracket> brackets = [];
        try
        {
            int lineNumber = 0;
            foreach (string lineRead in File.ReadLines(fileName))
            {
                lineNumber++;
                string line = lineRead.Trim();
                // las líneas vacías se ignoran
                if (line == "")
                {
                    continue;
                }
                // la línea debe tener tres campos
                string[] fields = Separator().Split(line);
                if (fields.Length != 3)
                {
                    throw new TaxException($"Line no. {lineNumber} is incorrect ({line})")
                    {
                        Code = (int)ErrorCode.Line
                    };
                }
                // tres números decimales positivos o cero, escritos con punto 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
                    };
                }
                // almacenamos el nuevo tramo del impuesto
                brackets.Add(new TaxBracket(limit, coeffR, coeffN));
            }
        }
        catch (Exception e) when (e is IOException or UnauthorizedAccessException)
        {
            // error de acceso al archivo: lo envolvemos en una TaxException
            throw new TaxException($"Error while reading the file {name}", e)
            {
                Code = (int)ErrorCode.Access
            };
        }
        // se necesita al menos un tramo
        if (brackets.Count == 0)
        {
            throw new TaxException($"The file {name} does not contain any bracket")
            {
                Code = (int)ErrorCode.Line
            };
        }
        // transferimos la lista al arreglo de tramos
        taxBrackets = brackets.ToArray();
    }

    // conversión de un campo a decimal >= 0, sin importar la cultura de la máquina
    private static bool Read(string field, out decimal result) =>
        decimal.TryParse(field, NumberStyles.AllowDecimalPoint, CultureInfo.InvariantCulture, out result);
}

Comentarios:

  • línea 7: la clase [FileTax] deriva de la clase [AbstractTax], al igual que la clase [HardwiredTax] en la versión 2. Se declara como [partial] porque contiene una expresión regular generada;
  • líneas 10–11: la expresión regular del separador de campos en una línea limit:coeffR:coeffN: el carácter [:], precedido y seguido de cualquier cantidad de espacios;
  • líneas 14–17: los tramos leídos, devueltos por la propiedad [TaxBrackets], que redefine la propiedad abstracta de [AbstractTax];
  • línea 19: el constructor recibe el nombre del archivo de texto que contiene los datos. Su función es llenar la matriz [taxBrackets];
  • línea 22: el nombre del archivo sin su ruta, que se usa en los mensajes de error. En realidad, el constructor recibe una ruta completa, que no es necesario mostrar al usuario;
  • línea 24: la lectura de un archivo de texto es secuencial: el número de líneas no se conoce hasta haber leído todo el archivo. Por lo tanto, no se puede dimensionar la matriz de antemano; los tramos se almacenan temporalmente en una lista;
  • línea 28: el archivo se lee línea por línea con [File.ReadLines], que abre y cierra el archivo por sí mismo. El curso de 2008 usaba [StreamReader];
  • líneas 38–43: la línea se divide en campos mediante una expresión regular; si no hay tres campos, se lanza una excepción [TaxException] con el código [Line] . El curso de 2008 guardaba el error en una variable, salía del bucle y lanzaba la excepción después de cerrar el archivo: lanzarla de inmediato es más simple, y [File.ReadLines] cierra el archivo en cualquier caso, ya que el bucle [foreach] libera su enumerador incluso cuando una excepción lo interrumpe;
  • líneas 47–55: conversión de los tres campos a números decimales. Los errores se acumulan en la variable [code] mediante el operador [|=] y luego se informan juntos;
  • líneas 83–84: conversión de un campo. [NumberStyles.AllowDecimalPoint] solo permite dígitos y un punto decimal: sin signos, espacios ni separadores de miles. Por lo tanto, los números negativos se rechazan, lo que valida los datos al mismo tiempo que se convierten. [CultureInfo.InvariantCulture] impone el punto como separador decimal, sea cual sea la configuración regional de la máquina;
  • líneas 62–67: los errores de acceso al archivo ([IOException] y sus variantes, como [FileNotFoundException], o [UnauthorizedAccessException] por permisos insuficientes) se encapsulan en una [TaxException] con el código [Access]. El [when (...)] filtro de excepciones (C# 6) intercepta solo estas excepciones: las excepciones [TaxException] lanzadas dentro del bucle no se interceptan y salen del constructor sin cambios. El patrón [e is IOException or UnauthorizedAccessException] es un patrón combinado que usa [or] (C# 9);
  • líneas 71–79: un archivo vacío se rechaza; de lo contrario, la lista se transfiere a la matriz de tramos, que era el objetivo del constructor.

Encapsular las excepciones de bajo nivel ([IOException]) en una excepción específica de la aplicación ([TaxException]) permite que el código que llama maneje un solo tipo de excepción, sea cual sea la fuente de datos: un archivo de texto, un archivo JSON y, más adelante en el curso, una base de datos.

5.9.4. La clase JsonTax

La clase [JsonTax] proporciona los tramos leídos de un archivo JSON:

using System.Text.Json;

namespace TaxV3;

// los tramos del impuesto leídos de un archivo JSON
public class JsonTax : AbstractTax
{
    // opciones "Web": nombres de propiedades en camelCase (limit, coeffR, coeffN)
    private static readonly JsonSerializerOptions options = new(JsonSerializerDefaults.Web);

    // los tramos del impuesto leídos del archivo
    private readonly TaxBracket[] taxBrackets;

    // implementación de la propiedad abstracta de la clase padre
    protected override TaxBracket[] TaxBrackets => taxBrackets;

    public JsonTax(string fileName)
    {
        // el nombre del archivo, sin su ruta, para los mensajes de error
        string name = Path.GetFileName(fileName);
        string json;
        try
        {
            // lectura del archivo
            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
        {
            // deserialización del arreglo de tramos
            brackets = JsonSerializer.Deserialize<TaxBracket[]>(json, options);
        }
        catch (JsonException e)
        {
            throw new TaxException($"The file {name} is incorrect: {e.Message}", e)
            {
                Code = (int)ErrorCode.Json
            };
        }
        // se necesita al menos un tramo, sin ningún 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;
    }
}

Comentarios:

  • línea 9: las opciones “Web”: las propiedades JSON [limit], [coeffR] y [coeffN] corresponden a las propiedades [Limit], [CoeffR] y [CoeffN] de la estructura [TaxBracket] sin necesidad de modificar esta última con atributos. Las opciones se almacenan en un campo estático: un objeto [JsonSerializerOptions] guarda información sobre los tipos que ha procesado, y se recomienda reutilizarlo;
  • líneas 25–31: lectura del archivo; un error de acceso se maneja como en [FileTax];
  • línea 38: una sola instrucción convierte el texto JSON en una matriz de tramos. [System.Text.Json] sabe construir una estructura de tipo registro llamando a su constructor. Un documento no válido provoca una [JsonException], encapsulada dentro de una [TaxException] con el código [Json];
  • líneas 48–57: la deserialización verifica el formato del documento, no la validez de los datos: queda por verificar que haya al menos un tramo (el documento [null] o [] es un JSON válido) y que no haya valores negativos. El método LINQ [Any] realiza esta última verificación en una sola línea.

Comparar las dos clases es instructivo: con un formato de datos estructurado y una biblioteca que lo entiende, el análisis del archivo ya no requiere ningún código.

5.9.5. El programa principal

El proyecto de consola [TaxV3] tiene la siguiente estructura de directorios:

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

El archivo de proyecto [TaxV3.csproj] es el creado por [dotnet new console], al que se ha añadido un grupo de elementos:

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

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

  <!-- los archivos de datos se copian junto al ejecutable -->
  <ItemGroup>
    <None Update="TaxData*.txt;TaxData*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>

El elemento [<None Update="..." CopyToOutputDirectory="PreserveNewest" />] (línea 12) especifica que los archivos de datos deben copiarse a la carpeta del ejecutable ([bin/Debug/net10.0]) durante la compilación si son más recientes que la copia existente. El carácter [*] permite especificar de una vez todos los archivos [TaxData*.txt] y [TaxData*.json] . Esto equivale a la propiedad “Copiar en el directorio de salida” que el curso de 2008 establecía en las propiedades del archivo en Visual Studio.

El programa [Program.cs] es el siguiente:

using TaxV3;

// cálculo del impuesto, versión 3: los tramos del impuesto se leen de un archivo
// sintaxis: dotnet run [-- archivo]; archivo: TaxData.txt por defecto, o un archivo .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
    """;

// el archivo de datos se busca junto al ejecutable
string fileName = args.Length > 0 ? args[0] : "TaxData.txt";
string path = Path.Combine(AppContext.BaseDirectory, fileName);
Console.WriteLine($"Tax brackets read from [{fileName}]");

// creación de un objeto ITax; la clase depende de la extensión del archivo
ITax tax;
try
{
    tax = Path.GetExtension(fileName).ToLower() switch
    {
        ".json" => new JsonTax(path),
        _ => new FileTax(path)
    };
}
catch (TaxException e)
{
    // visualización del error; el código se muestra como una combinación 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}]");
    // detención del programa
    return 1;
}

// bucle de entrada
while (true)
{
    // se piden los parámetros del cálculo del impuesto
    Console.Write("Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: ");
    string parameters = (Console.ReadLine() ?? "").Trim();
    // ¿algo que hacer?
    if (parameters == "")
    {
        break;
    }
    // verificación del número de campos de la línea escrita
    string[] fields = parameters.Split(' ', StringSplitOptions.RemoveEmptyEntries);
    if (fields.Length != 3)
    {
        Console.WriteLine(syntax);
        continue;
    }
    // verificación de la validez de los 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;
    }
    // los parámetros son correctos: calculamos el impuesto
    Console.WriteLine($"Tax={tax.Calculate(married == "y", nbChildren, salary)} euros");
}
return 0;

Comentarios:

  • línea 14: el nombre del archivo de datos se pasa como argumento; de forma predeterminada, es [TaxData.txt];
  • línea 15: el archivo se busca en la carpeta del ejecutable, [AppContext.BaseDirectory], donde se copió durante la compilación. Así, el programa encuentra sus datos sea cual sea la carpeta desde la que se lance, lo que no ocurría con las aplicaciones de un solo archivo de este capítulo;
  • líneas 22–25: una expresión [switch] (capítulo 3) selecciona la clase que se va a instanciar según la extensión del archivo. Las dos ramas devuelven tipos distintos, [JsonTax] and [FileTax]: el compilador infiere el tipo de la expresión a partir de la variable de destino [tax], que es de tipo [ITax] (expresión [switch] con tipo de destino). El resto del programa solo conoce la interfaz [ITax] y desconoce el origen de los datos;
  • líneas 28–34: la creación del objeto puede provocar una [TaxException], que se muestra antes de que el programa termine. El código se convierte a [ErrorCode] para mostrarse en texto legible; la excepción original, si la hay, se identifica por su tipo (su mensaje contiene la ruta completa del archivo);
  • líneas 37–76: el bucle de diálogo es exactamente el mismo que en la versión 2.

5.9.6. Ejecuciones

Con el archivo [TaxData.txt], de forma predeterminada:

> 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: 

Se reproducen los valores de las versiones anteriores: 4282 euros para una pareja casada con 2 hijos, 2959 euros con 3 hijos y 11 519 euros para una persona soltera sin hijos, con un salario anual de 60 000 euros. Las entradas incorrectas se señalan como en la versión 2.

Con el archivo [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: 

Con un archivo [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]

Con el siguiente archivo [TaxDataInvalid.txt], en el que la tercera línea usa una coma 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)]

Los campos 2 y 3 de la línea 3 se rechazan: el código de error es la combinación “Field2, Field3”. El campo 1 (14753), que no tiene parte decimal, es correcto.

Con el siguiente archivo, [TaxDataInvalid.json], en el que un coeficiente está escrito como cadena:

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]

El mensaje de [JsonException] especifica la ubicación exacta del error: la propiedad [coeffR] del segundo elemento de la matriz ([$[1].coeffR]), [LineNumber: 2], es decir, la tercera línea del documento, ya que [System.Text.Json] numera las líneas a partir de 0.

5.10. Conclusión

Este capítulo ha presentado las clases de .NET que se usan en casi todos los programas:

  • las cadenas inmutables ([string]) y las cadenas mutables ([StringBuilder]) para construirlas pieza por pieza; la interpolación con anchos y formatos, las cadenas sin formato (raw); las vistas ([ReadOnlySpan<char>]) para el código crítico;
  • las matrices y la clase [Array];
  • las colecciones genéricas [List<T>], [Dictionary<TKey,TValue>], [HashSet<T>], [Queue<T>], [Stack<T>], [PriorityQueue<TElement,TPriority>] y sus interfaces de solo lectura; las colecciones no genéricas [ArrayList] y [Hashtable] están obsoletas;
  • LINQ, sus secuencias [IEnumerable<T>], sus iteradores y su ejecución diferida;
  • los archivos de texto ([StreamReader], [StreamWriter], [File]), los archivos binarios ([BinaryWriter], [BinaryReader]) y la serialización JSON, que reemplaza la serialización binaria de [BinaryFormatter], eliminada de .NET;
  • las expresiones regulares, preferentemente generadas en tiempo de compilación y siempre protegidas por un tiempo de espera al procesar datos externos.

La aplicación de ejemplo ahora lee sus datos de un archivo de texto o JSON. El siguiente capítulo la reorganiza en capas: la lectura de datos, el cálculo de impuestos y la interacción con el usuario se convertirán en componentes independientes.