El Lenguaje de Programación Rust

por Steve Klabnik, Carol Nichols y Chris Krycho, con contribuciones de la Comunidad Rust

Esta versión del texto asume que estás usando Rust 1.82.0 (lanzado 2024-10-17) o posterior. Vea la sección “Instalación” del Capítulo 1 para instalar o actualizar Rust.

El formato HTML está disponible en línea en https://doc.rust-lang.org/stable/book/ y offline con instalaciones de Rust realizadas con rustup; ejecute rustup doc --book para abrir.

También están disponibles varias traducciones de la comunidad.

Este texto está disponible en formato de libro impreso y ebook de No Starch Press.

🚨 ¿Quieres una experiencia de aprendizaje más interactiva? Prueba una versión diferente del Libro de Rust, con: cuestionarios, resaltado, visualizaciones y más: https://rust-book.cs.brown.edu (en inglés)

Prefacio

No siempre fue tan claro, pero el lenguaje de programación Rust es fundamentalmente sobre empoderamiento: no importa qué tipo de código estás escribiendo ahora, Rust te empodera para llegar más lejos, para programar con confianza en una mayor variedad de dominios de lo que lo hiciste antes.

Tomemos, por ejemplo, el trabajo de “sistemas” que se ocupa de los detalles de bajo nivel de la administración de la memoria, la representación de datos y la concurrencia. Tradicionalmente, este reino de la programación se ve como arcano, accesible sólo a unos pocos que han dedicado los años necesarios para aprender a evitar sus infames trampas. Y aunque aquellos que lo practican lo hacen con precaución, para que su código no esté abierto a vulnerabilidades que puedan ser explotadas, caídas o corrupción.

Rust rompe estas barreras al eliminar las antiguas trampas y proporciona un conjunto amigable y pulido de herramientas para ayudarte en el camino. Los programadores que necesitan “sumergirse” en un control de bajo nivel pueden hacerlo con Rust, sin asumir el riesgo habitual de caídas o agujeros de seguridad, y sin tener que aprender los puntos finos de una cadena de herramientas caprichosa. Lo mejor de todo, el lenguaje está diseñado para guiarte naturalmente hacia un código confiable que es eficiente en términos de velocidad y uso de memoria.

Los programadores que ya están trabajando con código de bajo nivel pueden usar Rust para elevar sus ambiciones. Por ejemplo, introducir la paralelización en Rust es una operación relativamente de bajo riesgo: el compilador lo detectará por ti. Así puedes abordar optimizaciones más agresivas en tu código con la confianza de que no introducirás accidentalmente caídas o vulnerabilidades.

Pero Rust no se limita a la programación de sistemas de bajo nivel. Es lo suficientemente expresivo y ergonómico para hacer que las aplicaciones CLI, servidores web y muchos otros tipos de código sean bastante agradables de escribir - encontrarás ejemplos simples de ambos más adelante en el libro. Trabajar con Rust te permite desarrollar habilidades que se transfieren de un dominio a otro; puedes aprender Rust escribiendo una aplicación web, y luego aplicar esas mismas habilidades para dirigir tu Raspberry Pi.

Este libro abraza plenamente el potencial de Rust para empoderar a tus usuarios. Es un texto amigable y accesible que tiene como objetivo ayudarte a mejorar no sólo tu conocimiento de Rust, sino también tu alcance y confianza como programador en general. Así que sumérgete, prepárate para aprender y ¡bienvenido a la comunidad Rust!

— Nicholas Matsakis y Aaron Turon

Introducción

Nota: Esta edición del libro es la misma que The Rust Programming Language disponible en formato impreso y ebook de No Starch Press.

Bienvenido a El Lenguaje de Programación Rust, un libro introductorio sobre Rust. El lenguaje de programación Rust te ayuda a escribir software más rápido y confiable. La ergonomía de alto nivel y el control de bajo nivel a menudo están en conflicto en el diseño de lenguajes de programación; Rust desafía ese conflicto. A través del equilibrio entre una capacidad técnica poderosa y una gran experiencia de desarrollo, Rust te da la opción de controlar los detalles de bajo nivel (como el uso de memoria) sin todo el problema tradicionalmente asociado con tal control.

Para Quién Es Rust

Rust es ideal para muchas personas por una variedad de razones. Veamos algunos de los grupos más importantes.

Equipos de Desarrolladores

Rust está demostrando ser una herramienta productiva para colaborar entre equipos grandes de desarrolladores con diferentes niveles de conocimiento de programación de sistemas. El código de bajo nivel tiende a tener varios sutiles errores, que en la mayoría de otros lenguajes solo pueden ser detectados a través de pruebas extensivas y una revisión cuidadosa del código por parte de desarrolladores experimentados. En Rust, el compilador juega un rol de guardián al negarse a compilar código con estos errores elusivos, incluidos los errores de concurrencia. Trabajando junto al compilador, el equipo puede dedicar su tiempo a enfocarse en la lógica del programa en lugar de perseguir errores.

Rust también trae herramientas de desarrollo contemporáneas al mundo de la programación de sistemas:

• Cargo, el administrador de dependencias y herramienta de compilación incluido, hace que agregar, compilar y administrar dependencias sea fácil y consistente en todo el ecosistema de Rust.
• La herramienta de formateo Rustfmt garantiza un estilo de codificación consistente entre los desarrolladores.
• El servidor de lenguaje Rust proporciona integración con entornos de desarrollo integrado (IDE) para la finalización del código y los mensajes de error en línea.

Al usar estas y otras herramientas en el ecosistema de Rust, los desarrolladores pueden ser productivos mientras escriben código de nivel de sistemas.

Estudiantes

Rust es para estudiantes y quienes estén interesados en aprender sobre conceptos de sistemas. Usando Rust, muchas personas han aprendido sobre temas como el desarrollo de sistemas operativos. La comunidad es muy acogedora y feliz de responder preguntas de estudiantes. A través de esfuerzos como este libro, los equipos de Rust quieren hacer que los conceptos de sistemas sean más accesibles para más personas, especialmente para quienes son nuevos en la programación.

Empresas

Cientos de empresas, grandes y pequeñas, usan Rust en producción para una variedad de tareas, incluidas herramientas de línea de comandos, servicios web, herramientas de DevOps, dispositivos incrustados, análisis y transcodificación de audio y video, criptomonedas, bioinformática, motores de búsqueda, aplicaciones de Internet de las cosas, aprendizaje automático e incluso partes importantes del navegador web Firefox.

Desarrolladores de Código Abierto

Rust es para personas que quieren construir el lenguaje de programación Rust, la comunidad, las herramientas de desarrollo y las bibliotecas. Nos encantaría que contribuyeras al lenguaje Rust.

Personas que Valoran la Velocidad y la Estabilidad

Rust es para personas que anhelan velocidad y estabilidad en un lenguaje. Por velocidad, nos referimos tanto a la rapidez con que el código Rust puede ejecutarse como a la velocidad con que Rust te permite escribir programas. Las verificaciones del compilador de Rust garantizan la estabilidad a través de adiciones de funcionalidades y refactorizaciones. Esto contrasta con el código heredado quebradizo en lenguajes sin estas verificaciones, que los desarrolladores a menudo tienen miedo de modificar. Al esforzarse por lograr abstracciones de costo cero, características de alto nivel que se compilan en código de bajo nivel tan rápido como el código escrito manualmente, Rust se esfuerza por hacer que el código seguro sea también código rápido.

El lenguaje Rust también espera apoyar a muchos otros usuarios; los mencionados aquí son solo algunos de los principales interesados. En general, la mayor ambición de Rust es eliminar los compromisos que los programadores han aceptado durante décadas al proporcionar seguridad y productividad, velocidad y ergonomía. Pruébalo y ve si sus elecciones funcionan para ti.

Para Quién Es Este Libro

Este libro asume que has escrito código en otro lenguaje de programación, pero no hace ninguna suposición sobre cuál es. Hemos intentado hacer que el material sea ampliamente accesible para aquellos de una amplia variedad de antecedentes en programación. No pasamos mucho tiempo hablando de lo que es la programación o cómo pensar sobre ella. Si eres completamente nuevo en la programación, sería mejor leer un libro que brinde una introducción específica a la programación.

Cómo Usar Este Libro

En general, este libro asume que lo estás leyendo en secuencia, de principio a fin. Los capítulos posteriores se basan en conceptos de los capítulos anteriores, y los capítulos anteriores pueden no profundizar en detalles sobre un tema en particular, pero volverán al tema en un capítulo posterior.

Encontrarás dos tipos de capítulos en este libro: capítulos de conceptos y capítulos de proyectos. En los capítulos de conceptos, aprenderás sobre un aspecto de Rust. En los capítulos de proyectos, construiremos programas pequeños juntos, aplicando lo que has aprendido hasta ahora. Los capítulos 2, 12 y 20 son capítulos de proyectos; el resto son capítulos de conceptos.

El capítulo 1 explica cómo instalar Rust, cómo escribir un programa “Hola, mundo!” Y cómo usar Cargo, el administrador de paquetes y herramienta de compilación de Rust. El capítulo 2 es una introducción práctica a la escritura de un programa en Rust, teniendo que construir un juego de adivinanzas. Aquí tratamos los conceptos a un nivel alto, y capítulos posteriores proporcionarán detalles adicionales. Si quieres ponerte manos a la obra de inmediato, el capítulo 2 es el lugar para eso. El capítulo 3 cubre las características de Rust que son similares a las de otros lenguajes de programación, y en el capítulo 4 aprenderás sobre el sistema de propiedad de Rust. Si eres un aprendiz particularmente meticuloso que prefiere aprender todos los detalles antes de pasar al siguiente, es posible que desees omitir el capítulo 2 y dirigirte directamente al capítulo 3, regresando al capítulo 2 cuando gustes trabajar en un proyecto aplicando los detalles que has aprendido.

El capítulo 5 discute las estructuras y los métodos, y el capítulo 6 cubre las enumeraciones, las expresiones match, y la construcción de flujo de control if let. Usarás estructuras y enumeraciones para crear tipos personalizados en Rust.

En el capítulo 7, aprenderás sobre el sistema de módulos de Rust y sobre las reglas de privacidad para organizar tu código y su interfaz de programación de aplicaciones (API) pública. El capítulo 8 discute algunas estructuras de datos de colección comunes que proporciona la biblioteca estándar, como vectores, cadenas y mapas hash. El capítulo 9 explora la filosofía y técnicas de manejo de errores de Rust.

El capítulo 10 se adentra en los genéricos, los traits y los lifetimes, que te dan el poder de definir código que se aplique a varios tipos. El capítulo 11 trata sobre las pruebas, que incluso con las garantías de seguridad de Rust, son necesarias para asegurar que la lógica de tu programa sea correcta. En el capítulo 12, construiremos nuestra propia implementación de un subconjunto de la funcionalidad del comando de línea de comandos grep que busca texto dentro de archivos. Para esto, usaremos muchos de los conceptos que discutimos en los capítulos anteriores.

El capítulo 13 explora las closures y los iteradores: características de Rust que provienen de los lenguajes de programación funcional. En el capítulo 14, examinaremos Cargo en más profundidad y hablaremos sobre las mejores prácticas para compartir tus bibliotecas con otros. El capítulo 15 discute los punteros inteligentes que proporciona la biblioteca estándar y las características que habilitan su funcionalidad.

En el capítulo 16, recorreremos diferentes modelos de programación concurrente y hablaremos sobre cómo Rust te ayuda a programar en múltiples hilos sin temor. En el capítulo 17 nos basaremos en eso, explorando la sintaxis async y await de Rust y el modelo de concurrencia ligero que admiten.

El capítulo 18 examina cómo los modismos de Rust se comparan con los principios de programación orientada a objetos con los que podrías estar familiarizado.

El capítulo 19 es una referencia a los patrones y el emparejamiento de patrones, que son formas poderosas de expresar ideas en todo programa de Rust. El capítulo 20 contiene un banquete de temas avanzados de interés, incluyendo Rust inseguro, macros y más sobre lifetimes, traits, tipos, funciones y closures.

En el capítulo 21, ¡completaremos un proyecto en el que implementaremos un servidor web de múltiples hilos de bajo nivel!

Finalmente, algunos apéndices contienen información útil sobre el lenguaje en un formato más de referencia. El apéndice A cubre las palabras clave de Rust, el apéndice B cubre los operadores y símbolos de Rust, el apéndice C cubre los traits derivables proporcionados por la biblioteca estándar, el apéndice D cubre algunas herramientas de desarrollo útiles, y el apéndice E explica las ediciones de Rust. En el apéndice F, puede encontrar traducciones del libro, y en el apéndice G cubriremos cómo se hace Rust y qué es Rust nightly.

No hay una forma incorrecta de leer este libro: ¡si quieres adelantarte, hazlo! Es posible que debas volver a los capítulos anteriores si experimentas alguna confusión. Pero haz lo que funcione para ti.

Una parte importante del proceso de aprendizaje de Rust es aprender a leer los mensajes de error que muestra el compilador: estos te guiarán hacia el código funcional. Por lo tanto, proporcionaremos muchos ejemplos que no se compilan junto con el mensaje de error que mostrará el compilador en cada situación. Ten en cuenta que si ingresas y ejecutas un ejemplo aleatorio, ¡es posible que no se compile! Asegúrate de leer el texto circundante para ver si el ejemplo que estás intentando ejecutar está destinado a error. Ferris también te ayudará a distinguir el código que no está destinado a funcionar:

Ferris	Significado
	¡Este código no compila!
	¡Este código provoca un pánico!
	Este código no produce el comportamiento deseado.

En la mayoría de las situaciones, te guiaremos a la versión correcta de cualquier código que no se compile.

Código fuente

Los archivos de origen de los que se genera este libro se pueden encontrar en GitHub.

Empezando

¡Empecemos tu viaje con Rust! Hay mucho que aprender, pero todo viaje comienza en algún lugar. En este capítulo, discutiremos:

• Instalación de Rust en Linux, macOS y Windows
• Escribir un programa que imprima Hola, mundo!
• Uso de cargo, el administrador de paquetes y sistema de compilación de Rust

Instalación

El primer paso es instalar Rust. Descargaremos Rust a través de rustup, una herramienta de línea de comandos para administrar las versiones de Rust y las herramientas asociadas. Necesitarás una conexión a Internet para la descarga.

Nota: Si prefieres no usar rustup por alguna razón, consulta la página Otros métodos de instalación de Rust para obtener más opciones.

Los siguientes pasos instalan la última versión estable del compilador de Rust. Las garantías de estabilidad de Rust aseguran que todos los ejemplos del libro que se compilan seguirán compilando con versiones más nuevas de Rust. La salida puede diferir ligeramente entre versiones porque Rust a menudo mejora los mensajes de error y las advertencias. En otras palabras, cualquier versión más nueva, estable de Rust que instales usando estos pasos debería funcionar como se espera con el contenido de este libro.

Notación de línea de comandos

En este capítulo y en todo el libro, mostraremos algunos comandos utilizados en la terminal. Las líneas que debes ingresar en una terminal comienzan con $. No necesitas escribir el carácter $; es el indicador de línea de comandos mostrado para indicar el comienzo de cada comando. Las líneas que no comienzan con $ generalmente muestran la salida del comando anterior. Además, los ejemplos específicos de PowerShell usarán > en lugar de $.

Instalación de rustup en Linux o macOS

Si estás utilizando Linux o macOS, abre una terminal y escribe lo siguiente

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

El comando descarga un script y comienza la instalación de la herramienta rustup, que instala la última versión estable de Rust. Es posible que se te solicite tu contraseña. Si la instalación es exitosa, aparecerá la siguiente línea:

Rust is installed now. Great!

También necesitarás un enlazador, que es un programa que Rust utiliza para unir sus salidas compiladas en un solo archivo. Es probable que ya lo tengas. Si obtienes errores de enlace, debes instalar un compilador C, que generalmente incluye un enlazador. Un compilador C también es útil porque algunos paquetes comunes de Rust dependen de código C y necesitarán un compilador C.

En macOS, puedes obtener un compilador C ejecutando:

$ xcode-select --install

Los usuarios de Linux deben instalar generalmente GCC o Clang, según la documentación de su distribución. Por ejemplo, si usas Ubuntu, puede instalar el paquete build-essential.

Instalación de rustup en Windows

En Windows, ve a https://www.rust-lang.org/tools/install y sigue las instrucciones para instalar Rust. En algún momento de la instalación, recibirás un mensaje para instalar Visual Studio. Este provee un linker y las bibliotecas nativas necesarias para compilar programas.

Para obtener las herramientas de compilación, deberás instalar Visual Studio. Cuando se te pregunte qué paquetes de trabajo instalar, incluye:

• “Desarrollo de escritorio con C ++”
• El SDK de Windows 10 o 11
• El componente de paquete de idioma inglés, junto con cualquier otro paquete de idioma de tu elección

El resto de este libro usa comandos que funcionan tanto en cmd.exe como en PowerShell. Si hay diferencias específicas, explicaremos cuál usar.

Si tu necesitas más ayuda con este paso, mira MSVC prerequisites o escríbenos en nuestro discord

Solución de problemas

Para verificar si has instalado Rust correctamente, abra una shell y escribe esta línea:

$ rustc --version

Deberías ver el número de versión, el hash de confirmación y la fecha de confirmación de la última versión estable que se ha publicado, en el siguiente formato:

rustc x.y.z (abcabcabc yyyy-mm-dd)

Si ves esta información, ¡has instalado Rust correctamente! Si no ves esta información, verifica que Rust esté en la variable de sistema %PATH% de la siguiente manera.

En Windows CMD, usa:

> echo %PATH%

En PowerShell, usa:

> echo $env:Path

En Linux y macOS, usa:

$ echo $PATH

Si todo está correcto y Rust aún no funciona, hay varios lugares donde puedes obtener ayuda. Obten información sobre cómo comunicarte con otros Rustaceans (un apodo tonto que nos llamamos a nosotros mismos) en la página de la comunidad.

Actualización y desinstalación

Una vez que Rust se instala a través de rustup, actualizar a una versión recién lanzada es fácil. Desde tu shell, ejecuta el siguiente script de actualización:

$ rustup update

Para desinstalar Rust y rustup, ejecuta el siguiente script de desinstalación desde tu shell:

$ rustup self uninstall

Documentación local

La instalación de Rust también incluye una copia local de la documentación para que puedas leerla sin conexión. Ejecuta rustup doc para abrir la documentación local en tu navegador.

En cualquier momento en que se proporcione un tipo o una función de la biblioteca estándar y no estés seguro de lo que hace o cómo usarlo, usa la documentación de la interfaz de programación de aplicaciones (API) para averiguarlo.

Editores de Texto y Entornos de Desarrollo Integrados

Este libro no asume qué herramientas usas para escribir código en Rust. ¡Casi cualquier editor de texto servirá! Sin embargo, muchos editores de texto y entornos de desarrollo integrados (IDEs) tienen soporte integrado para Rust. Siempre puedes encontrar una lista bastante actualizada de muchos editores e IDEs en la página de herramientas del sitio web de Rust.

¡Hola, mundo!

Ahora que has instalado Rust, es hora de escribir tu primer programa en Rust. Es tradicional cuando se aprende un nuevo lenguaje escribir un pequeño programa que imprima el texto ¡Hola, mundo! en la pantalla, ¡así que haremos lo mismo aquí!

Nota: Este libro asume una familiaridad básica con la línea de comandos. Rust no asume cosas específicas sobre tu editor o herramientas o dónde vive tu código, por lo que si prefieres usar un entorno de desarrollo integrado (IDE) en lugar de la línea de comandos, siéntete libre de usar tu IDE favorito. Muchos IDEs ahora tienen algún grado de soporte para Rust; consulta la documentación del IDE para obtener más detalles. El equipo de Rust se ha centrado en habilitar un gran soporte a IDEs a través de rust-analyzer. Consulta Apéndice D para obtener más detalles.

Creando un directorio de proyecto

Comenzarás creando un directorio para almacenar tu código Rust. A Rust no le importa dónde vive tu código, pero para los ejercicios y proyectos de este libro, sugerimos que hagas un directorio proyectos en tu directorio de inicio y mantengas todos tus proyectos allí.

Abre una terminal y escribe los siguientes comandos para crear un directorio proyectos y un directorio para el proyecto “¡Hola, mundo!” dentro del directorio proyectos.

Para Linux, macOS y PowerShell en Windows, escribe esto:

$ mkdir ~/proyectos
$ cd ~/proyectos
$ mkdir hola_mundo
$ cd hola_mundo

Para Windows CMD, escribe esto:

> mkdir "%USERPROFILE%\proyectos"
> cd /d "%USERPROFILE%\proyectos"
> mkdir hola_mundo
> cd hola_mundo

Escribir y ejecutar un programa en Rust

A continuación, crea un nuevo archivo de texto y llámalo main.rs. Los archivos Rust siempre terminan con la extensión .rs. Si estás usando más de una palabra en tu nombre de archivo, la convención es usar un guión bajo para separarlos. Por ejemplo, usa hola_mundo.rs en lugar de holamundo.rs.

Ahora abre el archivo main.rs que acabas de crear y escribe el código en el Listado 1-1.

fn main() {
    println!("¡Hola, mundo!");
}

Guarda el archivo y vuelve a la ventana de la terminal en el directorio ~/proyectos/hola_mundo. En Linux o macOS, escribe los siguientes comandos para compilar y ejecutar el archivo:

$ rustc main.rs
$ ./main
¡Hola, mundo!

En Windows, escribe el comando .\main.exe en lugar de ./main:

> rustc main.rs
> .\main.exe
¡Hola, mundo!

Independientemente de tu sistema operativo, la cadena ¡Hola, mundo! debe imprimirse en la terminal. Si no ves esta salida, consulta la parte “Solución de problemas” de la sección de Instalación para obtener formas de obtener ayuda.

Si ¡Hola, mundo! se imprimió, ¡felicidades! Acabas de escribir oficialmente un programa en Rust. Eso te convierte en un programador de Rust, ¡bienvenido!

Anatomía de un programa en Rust

Revisemos este programa “¡Hola, mundo!” en detalle. Aquí está la primera parte del rompecabezas:

fn main() {

}

Estas líneas definen una función llamada main. La función main es especial: siempre es el primer código que se ejecuta en cada programa ejecutable de Rust. Aquí, la primera línea declara una función llamada main que no tiene parámetros y no devuelve nada. Si hubiera parámetros, irían dentro de los paréntesis ().

El cuerpo de la función está envuelto en {}. Rust requiere llaves alrededor de todos los cuerpos de función. Es buena costumbre colocar la llave de apertura en la misma línea que la declaración de la función, agregando un espacio entre ambos.

Nota: Si deseas mantener un estilo estándar en todos los proyectos de Rust, puedes usar una herramienta de formateo automático llamada rustfmt para formatear tu código en un estilo particular (más sobre rustfmt en Apéndice D). El equipo de Rust ha incluido esta herramienta con la distribución estándar de Rust, como rustc, por lo que debería estar instalado en tu computadora.

El cuerpo de la función main contiene el siguiente código:

#![allow(unused)]
fn main() {
    println!("¡Hola, mundo!");
}

Esta línea hace todo el trabajo en este pequeño programa: imprime texto en la pantalla. Hay cuatro detalles importantes que hay que notar aquí.

Primero, el estilo de Rust es indentar con cuatro espacios, no con una tabulación.

Segundo, println! llamamos a una macro de Rust. Si hubiéramos llamado a una función en su lugar, habríamos ingresado println (sin el !). Discutiremos las macros de Rust en más detalle en el Capítulo 20. Por ahora, solo necesitas saber que usar un ! significa que estamos llamando a una macro en lugar de una función normal y que las macros no siempre siguen las mismas reglas que las funciones.

Tercero, ve la cadena "¡Hola, mundo!". Pasamos esta cadena como argumento a println!, y la cadena se imprime en la pantalla.

Cuarto, terminamos la línea con un punto y coma (;), lo que indica que esta expresión ha terminado y la siguiente está lista para comenzar. La mayoría de las líneas de código de Rust terminan con un punto y coma.

Compilar y ejecutar son pasos separados

Acabas de ejecutar un programa recién creado, así que examinemos cada paso en el proceso.

Antes de ejecutar un programa de Rust, debes compilarlo usando el compilador de Rust ingresando el comando rustc y pasándole el nombre de tu archivo de código fuente, así:

$ rustc main.rs

Si tienes un trasfondo en C o C ++, notarás que esto es similar a gcc o clang. Después de compilar con éxito, Rust genera un ejecutable binario.

En Linux, macOS y PowerShell en Windows, puedes ver el ejecutable ingresando el comando ls en tu shell:

$ ls
main  main.rs

En Linux y macOS, verás dos archivos. Con PowerShell en Windows, verás los mismos tres archivos que verías con CMD. Con CMD en Windows, ingresarías lo siguiente:

> dir /B %= la /B significa que solo mostrara los nombres de los archivos =%
main.exe
main.pdb
main.rs

Esto muestra el archivo de código fuente con la extensión .rs, el archivo ejecutable (main.exe en Windows, pero main en todas las otras plataformas), y, cuando se usa Windows, un archivo que contiene información de depuración con la extensión .pdb. Desde aquí, ejecuta el archivo main o main.exe, así:

$ ./main # o .\main.exe en Windows

Si tu main.rs es tu programa "¡Hola, mundo!", Esta línea imprime ¡Hola, mundo! en tu terminal.

Si estás más familiarizado con un lenguaje dinámico, como Ruby, Python o JavaScript, puede que no estés acostumbrado a compilar y ejecutar un programa como pasos separados. Rust es un lenguaje compilado de antemano, lo que significa que puedes compilar un programa y dar el ejecutable a otra persona, y pueden ejecutarlo incluso sin tener Rust instalado. Si le das a alguien un archivo .rb, .py o .js, necesitan tener una implementación de Ruby, Python o JavaScript instalada (respectivamente). Pero en esos lenguajes, sólo necesitas un comando para compilar y ejecutar tu programa. Todo depende de las concesiones hechas al momento de diseñar un lenguaje.

Solo compilar con rustc está bien para programas simples, pero a medida que tu proyecto crece, querrás administrar todas las opciones y facilitar el compartir tu código. A continuación, te presentaremos la herramienta Cargo, que te ayudará a escribir programas de Rust reales.

¡Hola, Cargo!

Cargo es el sistema de compilación y administrador de paquetes de Rust. La mayoría de los Rustaceans usan esta herramienta para administrar sus proyectos Rust porque Cargo maneja muchas tareas para ti, como compilar tu código, descargar las bibliotecas de las que depende tu código y compilar esas bibliotecas. (Llamamos dependencias a las bibliotecas de las que depende tu código).

Los programas Rust más simples, como el que hemos escrito hasta ahora, no tienen dependencias. Si hubiéramos construido el proyecto “¡Hola, mundo!” con Cargo, sólo usaría la parte de Cargo que maneja la compilación de tu código. A medida que escribas programas Rust más complejos, agregarás dependencias, y si comienzas un proyecto usando Cargo, agregar dependencias será mucho más fácil de hacer.

Debido a que la gran mayoría de los proyectos Rust usan Cargo, el resto de este libro asume que también estás usando Cargo. Cargo viene instalado con Rust si usaste los instaladores oficiales que se discuten en la sección “Installation”. Si instalaste Rust a través de algunos otros medios, verifica si Cargo está instalado ingresando lo siguiente en tu terminal:

$ cargo --version

Si ves un número de versión, ¡lo tienes! Si ves un error, como command not found, consulta la documentación de tu método de instalación para determinar cómo instalar Cargo por separado.

Creación de un proyecto con Cargo

Vamos a crear un nuevo proyecto usando Cargo y ver cómo difiere de nuestro proyecto original “¡Hola, mundo!”. Navega de vuelta a tu directorio proyectos (o dondequiera que hayas decidido almacenar tu código). Luego, en cualquier sistema operativo, ejecuta lo siguiente:

$ cargo new hello_cargo
$ cd hello_cargo

El primer comando crea un nuevo directorio y proyecto llamado hello_cargo. Hemos nombrado a nuestro proyecto hello_cargo, y Cargo crea sus archivos en un directorio con el mismo nombre.

Ve al directorio hello_cargo y lista los archivos. Verás que Cargo ha generado dos archivos y un directorio para nosotros: un archivo Cargo.toml y un directorio src con un archivo main.rs dentro.

También ha inicializado un nuevo repositorio Git junto con un archivo .gitignore. Los archivos Git no se generarán si ejecutas cargo new dentro de un repositorio Git existente; puedes anular este comportamiento usando cargo new --vcs=git.

Nota: Git es un sistema de control de versiones común. Puedes cambiar cargo new para usar un sistema de control de versiones diferente o ningún sistema de control de versiones usando la bandera --vcs. Ejecuta cargo new --help para ver las opciones disponibles.

Abre Cargo.toml en tu editor de texto de elección. Debería verse similar al código del Listado 1-2.

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

Este archivo está en el formato TOML (Tom’s Obvious, Minimal Language), que es el formato de configuración de Cargo.

La primera línea, [package], es un encabezado de sección que indica que las siguientes declaraciones están configurando un paquete. A medida que agreguemos más información a este archivo, agregaremos otras secciones.

Las próximas tres líneas establecen la información de configuración que Cargo necesita para compilar tu programa: el nombre, la versión y la edición de Rust que se usará. Hablaremos sobre la entrada edition en Apéndice E

La última línea, [dependencies], es el comienzo de una sección para que enumere cualquier dependencia de tu proyecto. En Rust, los paquetes de código se denominan crates. No necesitaremos otros crates para este proyecto, pero lo haremos en el primer proyecto del Capítulo 2, por lo que usaremos esta sección de dependencias hasta entonces.

Ahora abre src/main.rs y echa un vistazo:

Nombre de archivo: src/main.rs

fn main() {
    println!("Hello, world!");
}

¡Cargo ha generado un programa “Hello, world!”/“¡Hola, mundo!” para ti, ¡igual que el que escribimos enl Listado 1-1! Hasta ahora, las diferencias entre nuestro proyecto y el proyecto generado por Cargo son que Cargo colocó el código en el directorio src y tenemos un archivo de configuración Cargo.toml en el directorio superior.

Cargo espera que tus archivos de origen vivan dentro del directorio src. El directorio del proyecto de nivel superior es solo para archivos README, información de licencia, archivos de configuración y cualquier otra cosa que no esté relacionada con tu código. Usar Cargo te ayuda a organizar tus proyectos. Hay un lugar para todo, y todo está en su lugar.

Si comenzaste un proyecto que no usa Cargo, como hicimos con el proyecto “¡Hola, mundo!”, puedes convertirlo en un proyecto que sí use Cargo. Mueve el código del proyecto al directorio src y crea un archivo Cargo.toml adecuado. Una forma sencilla de obtener el archivo Cargo.toml es ejecutar cargo init, el cual lo creara automaticamente.

Construir y ejecutar un proyecto de Cargo

Ahora veamos qué es diferente cuando construimos y ejecutamos el programa “¡Hola, mundo!” con Cargo. ¡Desde tu directorio hello_cargo, construye tu proyecto ingresando el siguiente comando:

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

Este comando crea un archivo ejecutable en target/debug/hello_cargo (o target\debug\hello_cargo.exe en Windows) en lugar de en tu directorio actual. Debido a que la compilación predeterminada es una compilación de depuración, Cargo coloca el binario en un directorio llamado debug. Puedes llamar al ejecutable con este comando:

$ ./target/debug/hello_cargo # o .\target\debug\hello_cargo.exe en Windows
Hello, world!

Si todo va bien, Hello, world! debería imprimirse en la terminal. Ejecutar cargo build por primera vez también hace que Cargo cree un nuevo archivo en el nivel superior: Cargo.lock. Este archivo rastrea las versiones exactas de las dependencias de tu proyecto. Este proyecto no tiene dependencias, por lo que el archivo es un poco escaso. Nunca necesitarás cambiar este archivo manualmente; Cargo administra su contenido para ti.

Acabamos de construir un proyecto con cargo build y ejecutarlo con ./target/debug/hello_cargo, pero también podemos usar cargo run para compilar el código y luego llamar al ejecutable resultante en un solo comando:

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

Usar cargo run es más conveniente que tener que recordar ejecutar cargo build y luego usar la ruta completa al binario, por lo que la mayoría de los desarrolladores usan cargo run.

Ten en cuenta que esta vez no vimos salida que indicara que Cargo estaba compilando hello_cargo. Cargo supo que los archivos no habían cambiado, por lo que no volvió a construir, sino que solo ejecutó el binario. Si hubieras modificado tu código fuente, Cargo habría reconstruido el proyecto antes de ejecutarlo, y habrías visto esta salida:

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

Cargo también proporciona un comando llamado cargo check. Este comando comprueba rápidamente tu código para asegurarse de que compila, pero no produce un ejecutable:

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

¿Por qué no querrías un ejecutable? A menudo, cargo check es mucho más rápido que cargo build porque omite el paso de producir un ejecutable. Si estás verificando continuamente tu trabajo mientras escribes el código, usar cargo check acelerará el proceso de informarte si tu proyecto todavía aún está compilando. ¡Por lo tanto, muchos Rustaceans ejecutan cargo check periódicamente mientras escriben su programa para asegurarse de que compila! Luego ejecutan cargo build cuando están listos para usar el ejecutable.

Resumamos lo que hemos aprendido hasta ahora sobre Cargo:

• Podemos crear un proyecto usando cargo new.
• Podemos construir un proyecto usando cargo build.
• Podemos construir y ejecutar un proyecto en un solo paso usando cargo run.
• Podemos construir un proyecto sin producir un binario para verificar errores usando cargo check.
• En lugar de guardar el resultado de la compilación en el mismo directorio que nuestro código, Cargo lo almacena en el directorio target/debug.

Una ventaja adicional de usar Cargo es que los comandos son los mismos sin importar en qué sistema operativo estés trabajando. Por lo tanto, en este punto, ya no proporcionaremos instrucciones específicas para Linux y macOS versus Windows.

Construyendo una versión de lanzamiento

Cuando tu proyecto finalmente esté listo para su lanzamiento, puedes usar cargo build --release para compilarlo con optimizaciones. Este comando creará un ejecutable en target/release en lugar de target/debug. Las optimizaciones hacen que tu código Rust se ejecute más rápido, pero al activarlos se alarga el tiempo que tarda tu programa en compilarse. Es por eso que hay dos perfiles diferentes: uno para el desarrollo, cuando deseas reconstruir rápidamente y con frecuencia, y otro para construir el programa final que le darás al usuario, que no se reconstruirá repetidamente y que se ejecutará lo más rápido posible. Si estás midiendo el tiempo de ejecución de tu código, asegúrate de ejecutar cargo build --release y realizar la prueba de rendimiento con el ejecutable en target/release.

Cargo como convención

Con proyectos simples, Cargo no proporciona mucho valor por sobre sólo usar rustc, pero demostrará su valor a medida que tus programas se vuelvan más intrincados. Una vez que los programas crecen a múltiples archivos o necesitan una dependencia, es mucho más fácil dejar que Cargo coordine la construcción.

Aunque el proyecto hello_cargo es simple, ahora usas muchas de las herramientas reales que usarás en el resto de tu carrera en Rust. De hecho, para trabajar en cualquier proyecto existente, puedes usar los siguientes comandos para verificar el código usando Git, cambiar al directorio del proyecto y construir:

$ git clone example.org/someproject
$ cd someproject
$ cargo build

Para obtener más información sobre Cargo, consulta su documentación.

Resumen

¡Ya estás en un gran comienzo en tu viaje de Rust! En este capítulo, has aprendido cómo:

• Instalar la última versión estable de Rust usando rustup
• Actualizar a una versión más reciente de Rust
• Abrir documentación instalada localmente
• Escribir y ejecutar un programa "¡Hola, mundo!" usando rustc directamente
• Crear y ejecutar un nuevo proyecto usando las convenciones de Cargo

Es un buen momento para construir un programa más sustancial para acostumbrarse a leer y escribir código Rust. Entonces, en el capítulo 2, construiremos un programa de juego de adivinanzas. Si prefieres comenzar aprendiendo cómo funcionan los conceptos de programación comunes en Rust, consulta el capítulo 3 y luego regresa al capítulo 2.

Programando un juego de adivinanzas

¡Vamos a empezar con Rust trabajando en un proyecto práctico! Este capítulo te introduce a algunos conceptos comunes de Rust mostrándote cómo usarlos en un programa real. ¡Aprenderás sobre let, match, métodos, funciones asociadas, paquetes externos y más! En los capítulos siguientes, exploraremos estos conceptos en más detalle. En este capítulo, solo practicarás los fundamentos.

Implementaremos un clásico problema de programación para principiantes: un juego de adivinanzas. Así es como funciona: el programa generará un número entero aleatorio entre 1 y 100. Luego le pedirá al jugador que ingrese una adivinanza. Después de ingresar una adivinanza, el programa indicará si la adivinanza es demasiado baja o demasiado alta. Si la adivinanza es correcta, el juego imprimirá un mensaje de felicitación y saldrá.

Configurando un nuevo proyecto

Para configurar un nuevo proyecto, vaya al directorio proyectos que creó en el Capítulo 1 y cree un nuevo proyecto usando Cargo, así:

$ cargo new guessing_game
$ cd guessing_game

El primer comando, cargo new, toma el nombre del proyecto (guessing_game) como el primer argumento. El segundo comando cambia al directorio del nuevo proyecto.

Mira el archivo Cargo.toml generado:

Nombre de archivo: Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"

[dependencies]

Como viste en el Capítulo 1, cargo new genera un programa “Hola, mundo!” para ti. Mira el archivo src/main.rs:

Nombre de archivo: src/main.rs

fn main() {
    println!("Hello, world!");
}

Ahora compilemos este programa “Hola, mundo!” y ejecutémoslo en el mismo paso usando el comando cargo run:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.20s
     Running `target/debug/guessing_game`
Hello, world!

El comando run es útil cuando necesitas iterar rápidamente en un proyecto, como haremos en este juego, probando rápidamente cada iteración antes de pasar a la siguiente.

Vuelve a abrir el archivo src/main.rs. Escribirás todo el código en este

Procesando una adivinanza

La primera parte del programa del juego de adivinanzas pedirá al usuario que ingrese un valor, procesará ese valor y verificará que el valor esté en el formato esperado. Para comenzar, permitiremos al jugador ingresar una adivinanza. Ingresa el código de la Lista 2-1 en src/main.rs.

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Este código contiene mucha información, así que repasémoslo línea por línea. Para obtener la entrada del usuario y luego imprimir el resultado como salida, necesitamos traer la biblioteca de entrada/salida io al alcance. La biblioteca io viene de la biblioteca estándar, conocida como std:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Por defecto, Rust tiene un conjunto de elementos definidos en la biblioteca estándar que trae al alcance de cada programa. Este conjunto se llama prelude, y puedes ver todo lo que contiene en la documentación de la biblioteca estándar.

Si un tipo que quieres usar no está en el prelude, tienes que traer ese tipo al alcance explícitamente con una declaración use. Usar la biblioteca std::io te proporciona una serie de características útiles, incluyendo la capacidad de aceptar la entrada del usuario.

Como viste en el Capítulo 1, la función main es el punto de entrada al programa:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

La sintaxis fn declara una nueva función; los paréntesis, (), indican que no hay parámetros; y la llave, {, inicia el cuerpo de la función.

Como también aprendiste en el Capítulo 1, println! es una macro que imprime una cadena en la pantalla:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Este código está imprimiendo una solicitud que indica qué es el juego y está solicitando la entrada del usuario.

Almacenando valores con variables

A continuación, crearemos una variable para almacenar la entrada del usuario, como esto:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

¡Ahora el programa está interesante! Hay mucho que está pasando en esta pequeña línea. Usamos la declaración let para crear la variable. Aquí hay otro ejemplo:

let apples = 5;

Esta línea crea una nueva variable llamada apples y la enlaza con el valor 5. En Rust, las variables son inmutables por defecto, lo que significa que una vez que le damos a la variable un valor, el valor no cambiará. Vamos a discutir este concepto en detalle en la sección “Variables y Mutabilidad” del Capítulo 3. Para hacer una variable mutable, agregamos mut antes del nombre de la variable:

let apples = 5; // immutable
let mut bananas = 5; // mutable

Nota: La sintaxis // inicia un comentario que continúa hasta el final de la línea. Rust ignora todo lo que está en los comentarios. Vamos a discutir los comentarios en más detalle en el Capítulo 3.

Regresando al programa del juego de adivinanzas, ahora sabes que let mut guess introducirá una variable mutable llamada guess. El signo igual (=) le dice a Rust que queremos enlazar algo a la variable ahora. A la derecha del signo igual está el valor al que guess está enlazado, que es el resultado de llamar a String::new, una función que devuelve una nueva instancia de un String. String es un tipo de cadena proporcionado por la biblioteca estándar que es una parte de texto codificada en UTF-8 que puede crecer.

La sintaxis :: en la línea ::new indica que new es una función asociada del tipo String. Una función asociada es una función que está implementada en un tipo, en este caso String. Esta función new crea una nueva cadena vacía. Encontrarás una función new en muchos tipos porque es un nombre común para una función que crea un nuevo valor de algún tipo.

En total, la línea let mut guess = String::new(); ha creado una variable mutable que está actualmente enlazada a una nueva instancia vacía de un String. ¡Uf!

Recibiendo la entrada del usuario

Recuerda que incluimos la funcionalidad de entrada/salida de la biblioteca estándar con use std::io; en la primera línea del programa. Ahora llamaremos a la función stdin del módulo io, que nos permitirá manejar la entrada del usuario:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Si no hubiéramos importado la biblioteca io con use std::io; al comienzo del programa, aún podríamos usar la función escribiendo esta llamada de función como std::io::stdin. La función stdin devuelve una instancia de std::io::Stdin, que es un tipo que representa un manejador de la entrada estándar para tu terminal.

A continuación, la línea .read_line(&mut guess) llama al método read_line en el manejador de entrada estándar para obtener la entrada del usuario. También estamos pasando &mut guess como argumento a read_line para decirle en qué cadena almacenar la entrada del usuario. El trabajo completo de read_line es tomar lo que el usuario escribe en la entrada estándar y agregar eso a una cadena (sin sobrescribir su contenido), por lo que, por lo tanto, pasamos esa cadena como argumento. La cadena de argumentos debe ser mutable para que el método pueda cambiar el contenido de la cadena.

El & indica que este argumento es una referencia, que te da una forma de permitir que varias partes de tu código accedan a una pieza de datos sin necesidad de copiar esos datos en la memoria varias veces. Las referencias son una característica compleja, y una de las principales ventajas de Rust es lo seguro y fácil que es usar referencias. No necesitas saber mucho de esos detalles para terminar este programa. Por ahora, todo lo que necesitas saber es que, como las variables, las referencias son inmutables por defecto. Por lo tanto, necesitas escribir &mut guess en lugar de &guess para hacerlo mutable. (El capítulo 4 explicará las referencias con más detalle.)

Manejando el posible fallo con Result

Todavía estamos trabajando en esta línea de código. Ahora estamos discutiendo una tercera línea de texto, pero ten en cuenta que aún es parte de una sola línea lógica de código. La siguiente parte es este método:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Podríamos haber escrito este código como:

io::stdin().read_line(&mut guess).expect("Failed to read line");

Sin embargo, una línea larga es difícil de leer, por lo que es mejor dividirla. A menudo es sabio introducir un salto de línea y otros espacios en blanco para ayudar a dividir líneas largas cuando llamas a un método con la sintaxis .method_name(). Ahora discutamos lo que hace esta línea.

Como se mencionó anteriormente, read_line coloca lo que el usuario ingresa en la cadena que le pasamos, pero también devuelve un valor Result. Result es una enumeración, a menudo llamada enum, que es un tipo que puede estar en uno de varios estados posibles. Llamamos a cada estado posible a una variante.

El Capítulo 6 cubrirá las enumeraciones con más detalles. El propósito de estos tipos Result es codificar información de manejo de errores.

Las variantes de Result son Ok y Err. La variante Ok indica que la operación fue exitosa, y dentro de Ok está el valor generado con éxito. La variante Err significa que la operación falló, y Err contiene información sobre cómo o por qué la operación falló.

Los valores del tipo Result, como los valores de cualquier tipo, tienen métodos definidos en ellos. Una instancia de Result tiene un método expect que puedes llamar. Si esta instancia de Result es un valor Err, expect hará que el programa se bloquee y muestre el mensaje que pasaste como argumento a expect. Si el método read_line devuelve un Err, probablemente sea el resultado de un error proveniente del sistema operativo subyacente. Si esta instancia de Result es un valor Ok, expect tomará el valor de retorno que Ok está sosteniendo y devolverá solo ese valor para que lo puedas usar. En este caso, ese valor es el número de bytes en la entrada del usuario.

Si no llamas a expect, el programa se compilará, pero obtendrás una advertencia:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `Result` that must be used
  --> src/main.rs:10:5
   |
10 |     io::stdin().read_line(&mut guess);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
   |
10 |     let _ = io::stdin().read_line(&mut guess);
   |     +++++++

warning: `guessing_game` (bin "guessing_game") generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.59s

Rust advierte que no has usado el valor Result devuelto por read_line, indicando que el programa no ha manejado un posible error.

La forma correcta de suprimir la advertencia es escribir realmente código de manejo de errores, pero en nuestro caso solo queremos bloquear este programa cuando ocurra un problema, por lo que podemos usar expect. Aprenderás a recuperarte de los errores en el Capítulo 9.

Imprimiendo valores con marcadores de posición println!

Además del corchete de cierre, solo hay una línea más que discutir en el código hasta ahora:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

Esta línea imprime la cadena que ahora contiene la entrada del usuario. El conjunto de llaves {} es un marcador de posición: piensa en {} como pequeñas pinzas de cangrejo que mantienen un valor en su lugar. Al imprimir el valor de una variable, el nombre de la variable puede ir dentro de las llaves curvas. Al imprimir el resultado de evaluar una expresión, coloca llaves curvas vacías en la cadena de formato, luego sigue la cadena de formato con una lista separada por comas de expresiones para imprimir en cada marcador de posición vacío de llaves curvas en el mismo orden. Imprimir una variable y el resultado de una expresión en una llamada a println! se vería así:

#![allow(unused)]
fn main() {
let x = 5;
let y = 10;

println!("x = {x} and y + 2 = {}", y + 2);
}

Este código imprimiría x = 5 and y + 2 = 12.

Probando la primera parte

Probemos la primera parte del juego de adivinanzas. Ejecútalo usando cargo run:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.44s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6

En este punto, la primera parte del juego está terminada: estamos obteniendo entrada del teclado y luego la imprimimos.

Generando un número secreto

A continuación, necesitamos generar un número secreto que el usuario intentará adivinar. El número secreto debe ser diferente cada vez para que el juego sea divertido de jugar más de una vez. Usaremos un número aleatorio entre 1 y 100 para que el juego no sea demasiado difícil. Rust aún no incluye la funcionalidad de números aleatorios en su biblioteca estándar. Sin embargo, el equipo de Rust proporciona un rand crate con dicha funcionalidad.

Usando un Crate para obtener más funcionalidad

Recuerda que un crate es una colección de archivos de código fuente de Rust. El proyecto que hemos estado construyendo es un binary crate, que es un ejecutable. El crate rand es un library crate, que contiene código que se pretende usar en otros programas y no se puede ejecutar por sí solo.

La coordinación de los crates externos de Cargo es donde realmente brilla Cargo. Antes de poder escribir código que use rand, necesitamos modificar el archivo Cargo.toml para incluir el crate rand como una dependencia. Abre ese archivo ahora y agrega la siguiente línea al final, debajo del encabezado de la sección [dependencies] que Cargo creó para ti. Asegúrate de especificar rand exactamente como lo tenemos aquí, con este número de versión, o los ejemplos de código en este tutorial pueden no funcionar:

Nombre de archivo: Cargo.toml

[dependencies]
rand = "0.8.5"

En el archivo Cargo.toml, todo lo que sigue a un encabezado es parte de esa sección que continúa hasta que comienza otra sección. En [dependencies] le dices a Cargo qué crates externos depende tu proyecto y qué versiones de esos crates requieres. En este caso, especificamos el crate rand con el especificador de versión semántica 0.8.5. Cargo entiende Semantic Versioning (a veces llamado SemVer), que es un estándar para escribir números de versión. El especificador 0.8.5 es realmente un atajo para ^0.8.5, lo que significa cualquier versión que sea al menos 0.8.5 pero inferior a 0.9.0.

Cargo considera que estas versiones tienen APIs públicas compatibles con la versión 0.8.5, y esta especificación asegura que obtendrá la última versión de corrección que aún se compilará con el código de este capítulo. Cualquier versión 0.9.0 o superior no está garantizada de tener la misma API que lo que usarán los siguientes ejemplos.

Ahora, sin cambiar ningún código, construyamos el proyecto, como se muestra en el Listado 2-2.

$ cargo build
    Updating crates.io index
     Locking 16 packages to latest compatible versions
      Adding wasi v0.11.0+wasi-snapshot-preview1 (latest: v0.13.3+wasi-0.2.2)
      Adding zerocopy v0.7.35 (latest: v0.8.9)
      Adding zerocopy-derive v0.7.35 (latest: v0.8.9)
  Downloaded syn v2.0.87
  Downloaded 1 crate (278.1 KB) in 0.16s
   Compiling proc-macro2 v1.0.89
   Compiling unicode-ident v1.0.13
   Compiling libc v0.2.161
   Compiling cfg-if v1.0.0
   Compiling byteorder v1.5.0
   Compiling getrandom v0.2.15
   Compiling rand_core v0.6.4
   Compiling quote v1.0.37
   Compiling syn v2.0.87
   Compiling zerocopy-derive v0.7.35
   Compiling zerocopy v0.7.35
   Compiling ppv-lite86 v0.2.20
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.69s

Es posible que veas números de versión diferentes (¡pero todos serán compatibles con el código, gracias a SemVer!) y líneas diferentes (dependiendo del sistema operativo), y las líneas pueden estar en un orden diferente.

Cuando incluimos una dependencia externa, Cargo obtiene las últimas versiones de todo lo que la dependencia necesita del registro, que es una copia de datos de Crates.io. Crates.io es donde las personas en el ecosistema de Rust publican sus proyectos de Rust de código abierto para que otros los utilicen.

Después de actualizar el registro, Cargo verifica la sección [dependencies] y descarga cualquier crate que se haya enumerado que aún no se haya descargado. En este caso, aunque solo enumeramos rand como una dependencia, Cargo también tomó otros crates que rand depende para funcionar. Después de descargar los crates, Rust los compila y luego compila el proyecto con las dependencias disponibles.

Si ejecuta cargo build nuevamente sin hacer ningún cambio, no obtendrá ninguna salida aparte de la línea Finished. Cargo sabe que ya ha descargado y compilado las dependencias, y no ha cambiado nada sobre ellas en su archivo Cargo.toml. Cargo también sabe que no ha cambiado nada sobre su código, por lo que tampoco lo vuelve a compilar. Sin nada que hacer, simplemente sale.

Si abre el archivo src/main.rs, realiza un cambio trivial y luego lo guarda y vuelve a construir, solo verá dos líneas de salida:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s

Estas líneas muestran que Cargo solo actualiza la compilación con su pequeño cambio en el archivo src/main.rs. Sus dependencias no han cambiado, por lo que Cargo sabe que puede reutilizar lo que ya ha descargado y compilado para esas.

Garantizar compilaciones reproducibles con el archivo Cargo.lock

Cargo tiene un mecanismo que le garantiza que puede reconstruir el mismo artefacto cada vez que usted o cualquier otra persona construye su código: Cargo solo usará las versiones de las dependencias que haya especificado hasta que indique lo contrario. Por ejemplo, digamos que la semana que viene sale la versión 0.8.6 del crate rand, y que esa versión contiene una corrección de error importante, pero también contiene una regresión que romperá su código. Para manejar esto, Rust crea el archivo Cargo.lock la primera vez que ejecuta cargo build, por lo que ahora tenemos esto en el directorio guessing_game

Cuando construye un proyecto por primera vez, Cargo determina todas las versiones de las dependencias que cumplen con los criterios y luego las escribe en el archivo Cargo.lock. Cuando construye su proyecto en el futuro, Cargo verá que el archivo Cargo.lock existe y usará las versiones especificadas allí en lugar de hacer todo el trabajo de averiguar las versiones nuevamente. Esto le permite tener una compilación reproducible de forma automática. En otras palabras, su proyecto permanecerá en 0.8.5 hasta que actualice explícitamente, gracias al archivo Cargo.lock. Debido a que el archivo Cargo.lock es importante para las compilaciones reproducibles, a menudo se verifica en el control de versiones con el resto del código en su proyecto.

Actualizar un crate para obtener una nueva versión

Cuando quiera actualizar un crate, Cargo proporciona el comando update, que ignorará el archivo Cargo.lock y determinará todas las últimas versiones que cumplan con sus especificaciones en Cargo.toml. Cargo luego escribirá esas versiones en el archivo Cargo.lock. En este caso, Cargo solo buscará versiones mayores que 0.8.5 y menores que 0.9.0. Si el crate rand ha lanzado las dos nuevas versiones 0.8.6 y 0.9.0, vería lo siguiente si ejecutara cargo update:

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

Cargo ignora el lanzamiento 0.9.0. En este punto, también notaría un cambio en su archivo Cargo.lock que indica que la versión del crate rand que ahora está usando es 0.8.6. Para usar la versión 0.9.0 o cualquier versión en la serie 0.9.x, tendría que actualizar el archivo Cargo.toml para que se vea así:

[dependencies]
rand = "0.9.0"

La próxima vez que ejecute cargo build, Cargo actualizará el registro de crates disponibles y volverá a evaluar sus requisitos de rand de acuerdo con la nueva versión que ha especificado.

Hay mucho más que decir sobre Cargo y su ecosistema, que discutiremos en el Capítulo 14, pero por ahora, eso es todo lo que necesita saber. Cargo hace muy fácil reutilizar bibliotecas, por lo que los Rustaceans pueden escribir proyectos más pequeños que se ensamblan a partir de un número de paquetes.

Generar un numero aleatorio

Comencemos a usar rand para generar un número para adivinar. El siguiente paso es actualizar src/main.rs, como se muestra en el Listado 2-3.

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Primero agregamos la línea use rand::Rng;. El trait Rng define métodos que los generadores de números aleatorios implementan, y este trait debe estar en el alcance para que podamos usar esos métodos. El Capítulo 10 cubrirá los traits en detalle.

A continuación, estamos agregando dos líneas en el medio. En la primera línea, llamamos a la función rand::thread_rng que nos da el generador de números aleatorios particular que vamos a usar: uno que es local al hilo de ejecución actual y está sembrado por el sistema operativo. Luego llamamos al método gen_range en el generador de números aleatorios. Este método está definido por el trait Rng que traemos al alcance con la declaración use rand::Rng;. El método gen_range toma una expresión de rango como argumento y genera un número aleatorio en el rango. El tipo de expresión de rango que estamos utilizando aquí toma la forma start..=end y es inclusivo en los límites inferior y superior, por lo que necesitamos especificar 1..=100 para solicitar un número entre 1 y 100.

Nota: No sabrá solo qué traits usar y qué métodos y funciones llamar desde un crate, por lo que cada crate tiene documentación con instrucciones para usarlo. Otra característica interesante de Cargo es que ejecutar el comando cargo doc --open construirá la documentación proporcionada por todas sus dependencias localmente y la abrirá en su navegador. Si está interesado en otra funcionalidad en el crate rand, por ejemplo, ejecute cargo doc --open y haga clic en rand en la barra lateral a la izquierda.

La segunda línea nueva imprime el número secreto. Esto es útil mientras desarrollamos el programa para poder probarlo, pero lo eliminaremos de la versión final. ¡No es mucho un juego si el programa imprime la respuesta tan pronto como comienza!

Intente ejecutar el programa varias veces:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5

Debería obtener números aleatorios diferentes, y todos deberían ser números entre 1 y 100. ¡Gran trabajo!

Comparando la Adivinanza con el Número Secreto

Ahora que tenemos la entrada del usuario y un número aleatorio, podemos compararlos. Ese paso se muestra en el Listado 2-4. Tenga en cuenta que este código aún no se compilará, como explicaremos.

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    // --snip--
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

Primero agregamos otra declaración use, que trae un tipo llamado std::cmp::Ordering al alcance de la biblioteca estándar. El tipo Ordering es otro enum y tiene las variantes Less, Greater y Equal. Estos son los tres resultados posibles cuando compara dos valores.

Luego agregamos cinco nuevas líneas al final que usan el tipo Ordering. El método cmp compara dos valores y se puede llamar en cualquier cosa que se pueda comparar. Toma una referencia a lo que quiera comparar: aquí está comparando guess con secret_number. Luego devuelve una variante del enum Ordering que importamos al alcance con la declaración use. Usamos una expresión match para decidir qué hacer a continuación basándonos en qué variante de Ordering se devolvió de la llamada a cmp con los valores en guess y secret_number.

Una expresión match está compuesta por brazos. Un brazo consta de un patrón para coincidir y el código que se debe ejecutar si el valor dado a match se ajusta al patrón del brazo. Rust toma el valor dado a match y busca cada patrón de brazo en orden. Los patrones y la construcción match son potentes características de Rust: le permiten expresar una variedad de situaciones que su código puede encontrar y se aseguran de que los maneje todos. Estas características se cubrirán en detalle en el Capítulo 6 y el Capítulo 19, respectivamente.

Vamos a repasar un ejemplo con la expresión match que usamos aquí. Digamos que el usuario ha adivinado 50 y el número secreto generado aleatoriamente esta vez es 38.

Cuando el código compara 50 con 38, el método cmp devolverá Ordering::Greater porque 50 es mayor que 38. La expresión match obtiene el valor Ordering::Greater y comienza a verificar el patrón de cada brazo. Mira el patrón del primer brazo, Ordering::Less, y ve que el valor Ordering::Greater no coincide con Ordering::Less, ¡así que ignora el código en ese brazo y se mueve al siguiente brazo! El patrón del siguiente brazo es Ordering::Greater, ¡que sí coincide con Ordering::Greater! El código asociado en ese brazo se ejecutará y mostrará Too big! en la pantalla. La expresión match termina después de la primera coincidencia exitosa, ¡así que no mirará el último brazo en este escenario.

Sin embargo, el código del Listado 2-4 aún no se compilará. Vamos a intentarlo:

$ cargo build
   Compiling libc v0.2.86
   Compiling getrandom v0.2.2
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.10
   Compiling rand_core v0.6.2
   Compiling rand_chacha v0.3.0
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
   --> src/main.rs:22:21
    |
22  |     match guess.cmp(&secret_number) {
    |                 --- ^^^^^^^^^^^^^^ expected `&String`, found `&{integer}`
    |                 |
    |                 arguments to this method are incorrect
    |
    = note: expected reference `&String`
               found reference `&{integer}`
note: method defined here
   --> file:///home/.rustup/toolchains/1.82/lib/rustlib/src/rust/library/core/src/cmp.rs:838:8
    |
838 |     fn cmp(&self, other: &Self) -> Ordering;
    |        ^^^

For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game` (bin "guessing_game") due to 1 previous error

El núcleo del error indica que hay tipos no coincidentes. Rust tiene un sistema de tipos fuerte y estático. Sin embargo, también tiene inferencia de tipo. Cuando escribimos let mut guess = String::new(), Rust pudo inferir que guess debería ser un String y no nos obligó a escribir el tipo. El secret_number, por otro lado, es un tipo de número. Algunos de los tipos de números de Rust pueden tener un valor entre 1 y 100: i32, un número de 32 bits; u32, un número sin signo de 32 bits; i64, un número de 64 bits; así como otros. A menos que se especifique lo contrario, Rust predetermina un i32, que es el tipo de secret_number a menos que agregue información de tipo en otro lugar que haga que Rust infiera un tipo numérico diferente. La razón del error es que Rust no puede comparar una cadena y un tipo numérico.

Finalmente, queremos convertir la String que el programa lee como entrada en un tipo de número real para que podamos compararlo numéricamente con el número secreto. Lo hacemos agregando esta línea al cuerpo de la función main:

Nombre de archivo: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    // --snip--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

La línea es:

let guess: u32 = guess.trim().parse().expect("Please type a number!");

Creamos una variable llamada guess. Pero espera, ¿no tiene el programa ya una variable llamada guess? Lo hace, pero Rust nos permite redefinir el valor anterior de guess con uno nuevo. Este concepto en Rust se le conoce como Shadowing, nos permite volver a usar el nombre de la variable guess en lugar de obligarnos a crear dos variables únicas, como guess_str y guess, por ejemplo. Lo cubriremos con más detalle en el Capítulo 3, pero por ahora, sé que esta característica se usa a menudo cuando desea convertir un valor de un tipo a otro tipo.

Enlazamos esta nueva variable a la expresión guess.trim().parse(). La guess en la expresión se refiere a la variable guess original que contenía la entrada como una cadena. El método trim en una instancia String eliminará cualquier espacio en blanco al principio y al final, lo que debemos hacer para poder comparar la cadena con el u32, que solo puede contener datos numéricos. El usuario debe presionar enter para satisfacer read_line e ingresar su conjetura, lo que agrega un carácter de nueva línea a la cadena. Por ejemplo, si el usuario escribe 5 y presiona enter, guess se ve así: 5\n. El \n representa "nueva línea". (En Windows, presionar enter resulta en un retorno de carro y una nueva línea, \r\n). El método trim elimina \n o \r\n, lo que resulta en solo 5.

El método parse en las cadenas convierte una cadena en otro tipo. Aquí, lo usamos para convertir de una cadena a un número. Debemos decirle a Rust el tipo de número exacto que queremos usando let guess: u32. Los dos puntos (:) después de guess le dicen a Rust que anotaremos el tipo de variable. Rust tiene algunos tipos de número integrados; el u32 visto aquí es un entero sin signo de 32 bits. Es una buena opción predeterminada para un número positivo pequeño. Aprenderá sobre otros tipos de números en el Capítulo 3.

Además, la anotación u32 en este programa de ejemplo y la comparación con secret_number significa que Rust inferirá que secret_number también debería ser u32. ¡Entonces la comparación será entre dos valores del mismo tipo!

El método parse solo funcionará en caracteres que se puedan convertir lógicamente en números y, por lo tanto, pueden causar fácilmente errores. Si, por ejemplo, la cadena contiene A👍%, no habría manera de convertir eso en un número. Debido a que podría fallar, el método parse devuelve un tipo Result, tal como lo hace el método read_line (discutido anteriormente en “Manejo de posibles fallas con Result”). Trataremos este Result de la misma manera usando el método expect de nuevo. Si parse devuelve una variante Err del tipo Result porque no pudo crear un número a partir de la cadena, la llamada expect hará que el juego se bloquee y muestre el mensaje que le damos. Si parse puede convertir exitosamente la cadena en un número, devolverá la variante Ok del tipo Result, y expect devolverá el número que queremos del valor Ok.

¡Corramos el programa ahora!

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
  76
You guessed: 76
Too big!

¡Bien! Aunque se agregaron espacios antes de la adivinanza, el programa aún sabía que el usuario adivinó 76. Ejecute el programa varias veces para verificar el comportamiento diferente con diferentes tipos de entrada: adivine el número correctamente, adivine un número que sea demasiado alto y adivine un número que sea demasiado bajo.

Tenemos la mayoría del juego funcionando ahora, pero el usuario solo puede adivinar una vez. ¡Cambiamos eso agregando un bucle!

Permitir múltiples adivinanzas con bucles

La palabra clave loop crea un bucle infinito. Agregaremos un bucle para darle a los usuarios más oportunidades para adivinar el número:

Nombre de archivo: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    // --snip--

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        // --snip--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => println!("You win!"),
        }
    }
}

Como puede ver, hemos movido todo desde la solicitud de entrada de adivinanzas hacia adelante en un bucle. Asegúrese de indentar las líneas dentro del bucle otras cuatro veces y ejecute el programa nuevamente. ¡El programa ahora pedirá otra adivinanza para siempre, lo que introduce un nuevo problema! ¡Parece que el usuario no puede salir!

El usuario siempre podría interrumpir el programa usando el atajo de teclado ctrl-c. Pero hay otra forma de escapar de este monstruo insaciable, como se mencionó en la discusión de parse en “Comparando la adivinanza con el número secreto”: si el usuario ingresa una respuesta que no es un número, el programa se bloqueará. Podemos aprovechar eso para permitir que el usuario salga, como se muestra aquí:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit
thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Al escribir quit se cerrará el juego, pero como notará, también lo hará al ingresar cualquier otra entrada que no sea un número. Esto es lo menos óptimo, para decir lo menos; queremos que el juego también se detenga cuando se adivine el número correcto.

Salir después de una adivinanza correcta

Programemos el juego para que se cierre cuando el usuario gane agregando una declaración break:

Nombre de archivo: src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Agregando la línea break después de You win! hace que el programa salga del bucle cuando el usuario adivina el número secreto correctamente. Salir del bucle también significa salir del programa, porque el bucle es la última parte de main.

Manejo de entrada no válida

Para mejorar aún más el comportamiento del juego, en lugar de bloquear el programa cuando el usuario ingresa un número no válido, hagamos que el juego ignore un número no válido para que el usuario pueda seguir adivinando. Podemos hacer eso alterando la línea donde guess se convierte de un String a un u32, como se muestra en el Listado 2-5.

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        // --snip--

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

Cambiamos de una llamada expect a una expresión match para pasar de bloquear el programa en un error a manejar el error. Recuerde que parse devuelve un tipo Result y Result es un enum que tiene las variantes Ok y Err. Aquí estamos usando una expresión match, como hicimos con el resultado Ordering del método cmp.

Si parse es capaz de convertir exitosamente la cadena en un número, devolverá un valor Ok que contiene el número resultante. Ese valor Ok coincidirá con el patrón de la primera rama y la expresión match devolverá el valor num que parse produjo y puso dentro del valor Ok. Ese número terminará en el lugar correcto en la nueva variable guess que estamos creando.

Si parse no es capaz de convertir la cadena en un número, devolverá un valor Err que contiene más información sobre el error. El valor Err no coincide con el patrón Ok(num) en la primera rama de match, pero sí coincide con el patrón Err(_) en la segunda rama. El guión bajo, _, es un valor de captura; en este ejemplo, estamos diciendo que queremos coincidir con todos los valores Err, sin importar qué información tengan dentro. ¡Así que el programa ejecutará el código de la segunda rama, continue, que le dice al programa que vaya a la siguiente iteración del loop y pida otra adivinanza. ¡Así que, efectivamente, el programa ignora todos los errores que parse puede encontrar!

Ahora todo en el programa debería funcionar como se espera. Vamos a probarlo:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!

¡Genial! Con un pequeño ajuste final, terminaremos el juego de adivinanzas. Recuerde que el programa todavía está imprimiendo el número secreto. Eso funcionó bien para las pruebas, pero arruina el juego. Vamos a eliminar el println! que muestra el número secreto. El listado 2-6 muestra el código final.

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

En este punto, ha construido exitosamente el juego de adivinanzas. ¡Felicidades!

Resumen

Este proyecto fue una manera práctica de introducirle a muchos nuevos conceptos de Rust: let, match, funciones, el uso de paquetes externos, y más. En los próximos capítulos, aprenderá sobre estos conceptos en más detalle. El capítulo 3 cubre conceptos que la mayoría de los lenguajes de programación tienen, como variables, tipos de datos y funciones, y muestra cómo usarlos en Rust. El capítulo 4 explora la propiedad, una característica que hace que Rust sea diferente de otros lenguajes. El capítulo 5 discute las estructuras y la sintaxis de los métodos, y el capítulo 6 explica cómo funcionan los enums.

Conceptos Comunes de Programación

Este capítulo cubre conceptos que aparecen en casi todos los lenguajes de programación y cómo funcionan en Rust. Muchos lenguajes de programación tienen mucho en común en su núcleo. Ninguno de los conceptos presentados en este capítulo son únicos de Rust, pero los discutiremos en el contexto de Rust y explicaremos las convenciones alrededor de su uso.

Específicamente, aprenderás sobre variables, tipos básicos, funciones, comentarios y flujo de control. Estas bases estarán en todos los programas de Rust, y aprenderlas temprano te dará un núcleo fuerte para comenzar.

Palabras clave

El lenguaje Rust tiene un conjunto de palabras clave que están reservadas para su uso exclusivo por el lenguaje, al igual que en otros lenguajes. Tenga en cuenta que no puede usar estas palabras como nombres de variables o funciones. La mayoría de las palabras clave tienen significados especiales, y las usará para realizar varias tareas en sus programas de Rust; algunas no tienen ninguna funcionalidad actual asociada con ellas, pero se han reservado para funcionalidad que podría agregarse a Rust en el futuro. Puede encontrar una lista de las palabras clave en Apéndice A.

Variables y Mutabilidad

Como se mencionó en la sección “Almacenando valores con variables” , por defecto, las variables son inmutables. Este es uno de los muchos empujes que Rust le da para que escriba su código de una manera que aproveche la seguridad y la fácil concurrencia que ofrece Rust. Sin embargo, todavía tiene la opción de hacer sus variables mutables. Exploremos cómo y por qué Rust le anima a favorecer la inmutabilidad y por qué a veces podría querer optar por no hacerlo.

Cuando una variable es inmutable, una vez que un valor está vinculado a un nombre, no puede cambiar ese valor. Para ilustrar esto, genere un nuevo proyecto llamado variables en su directorio proyectos usando cargo new variables.

Luego, en su nuevo directorio variables, abra src/main.rs y reemplace su código con el siguiente código, que aún no se compilará:

Nombre de archivo: src/main.rs

fn main() {
    let x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

Guarde y ejecute el programa usando cargo run. Debería recibir un mensaje de error relacionado con un error de inmutabilidad, como se muestra en esta salida:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0384]: cannot assign twice to immutable variable `x`
 --> src/main.rs:4:5
  |
2 |     let x = 5;
  |         - first assignment to `x`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable
  |
help: consider making this binding mutable
  |
2 |     let mut x = 5;
  |         +++

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` (bin "variables") due to 1 previous error

Este ejemplo muestra cómo el compilador le ayuda a encontrar errores en sus programas. Los errores de compilación pueden ser frustrantes, pero realmente solo significa que su programa aún no está realizando de manera segura lo que desea que haga; no significa que no es un buen programador! Los Rustaceans experimentados aún reciben errores de compilación.

Recibió el mensaje de error cannot assign twice to immutable variable `x` porque intentó asignar un segundo valor a la variable inmutable x.

Es importante que obtengamos errores en tiempo de compilación cuando intentamos cambiar un valor que está designado como inmutable, porque esta situación puede conducir a errores. Si una parte de nuestro código opera bajo la suposición de que un valor nunca cambiará y otra parte de nuestro código cambia ese valor, es posible que la primera parte del código no haga lo que estaba diseñado para hacer. La causa de este tipo de error puede ser difícil de rastrear después del hecho, especialmente cuando la segunda pieza de código cambia el valor solo algunas veces. El compilador de Rust garantiza que cuando afirma que un valor no cambiará, realmente no cambiará, por lo que no tiene que rastrearlo usted mismo. Su código es, por lo tanto, más fácil de razonar.

Pero la mutabilidad puede ser muy útil y puede hacer que el código sea más conveniente de escribir. Aunque las variables son inmutables por defecto, puede hacerlas mutables agregando mut delante del nombre de la variable como lo hizo en el Capitulo 2. Agregando mut también comunica la intención a los lectores futuros del código indicando que otras partes del código cambiarán el valor de esta variable.

Por ejemplo, cambiemos src/main.rs a lo siguiente:

Nombre de archivo: src/main.rs

fn main() {
    let mut x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

Cuando ejecutamos el programa ahora, obtenemos esto:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
The value of x is: 5
The value of x is: 6

Se nos permite cambiar el valor vinculado a x de 5 a 6 cuando se usa mut. En última instancia, decidir si usar o no la mutabilidad depende de usted y depende de lo que crea que es más claro en esa situación particular.

Constantes

Al igual que las variables inmutables, las constantes son valores que están vinculados a un nombre y no se les permite cambiar, pero hay algunas diferencias entre las constantes y las variables.

Primero, no se le permite usar mut con constantes. Las constantes no son solo inmutables por defecto, siempre son inmutables. Declara constantes usando la palabra clave const en lugar de la palabra clave let, y el tipo del valor debe estar anotado. Cubriremos los tipos y las anotaciones de tipo en la siguiente sección, “Tipos de datos”, por lo que no se preocupe por los detalles ahora. Solo sepa que siempre debe anotar el tipo.

Las constantes se pueden declarar en cualquier ámbito, incluido el ámbito global, lo que las hace útiles para valores que muchas partes del código necesitan conocer.

La última diferencia es que las constantes solo se pueden establecer en una expresión constante, no en el resultado de un valor que solo se podría calcular en tiempo de ejecución.

Aquí hay un ejemplo de una declaración constante:

#![allow(unused)]
fn main() {
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
}

El nombre de la constante es THREE_HOURS_IN_SECONDS y su valor se establece en el resultado de multiplicar 60 (el número de segundos en un minuto) por 60 (el número de minutos en una hora) por 3 (el número de horas que queremos contar en este programa). La convención de nombramiento de Rust para constantes es usar mayúsculas con guiones bajos entre palabras. El compilador es capaz de evaluar un conjunto limitado de operaciones en tiempo de compilación, lo que nos permite elegir escribir este valor de una manera que sea más fácil de entender y verificar, en lugar de establecer esta constante en el valor 10,800. Vea la "sección de la Referencia de Rust sobre la evaluación constante" para más información sobre qué operaciones se pueden usar al declarar constantes.

Las constantes son válidas durante todo el tiempo que se ejecuta un programa, dentro del ámbito en el que se declararon. Esta propiedad hace que las constantes sean útiles para los valores en el dominio de su aplicación que varias partes del programa podrían necesitar conocer, como el número máximo de puntos que cualquier jugador de un juego puede obtener o la velocidad de la luz.

Nombrar valores codificados en su programa como constantes es útil para transmitir el significado de ese valor a los futuros mantenedores del código. También ayuda a tener solo un lugar en su código en el que necesitaría cambiar si el valor codificado tuviera que actualizarse en el futuro.

Shadowing

Como vio en el tutorial del juego de adivinanzas en Capítulo 2, puede declarar una nueva variable con el mismo nombre que una variable anterior. Los Rustaceans dicen que la primera variable es ocultada por la segunda, lo que significa que la segunda variable es lo que el compilador verá cuando use el nombre de la variable. En efecto, la segunda variable oculta la primera, tomando cualquier uso del nombre de la variable para sí misma hasta que se haga shadowing sobre la misma variable o el ámbito finalice. Podemos ocultar una variable usando el mismo nombre de variable y repitiendo el uso de la palabra clave let de la siguiente manera:

Nombre de archivo: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }

    println!("The value of x is: {x}");
}

Este programa primero vincula a x el valor de 5. Luego crea una nueva variable x repitiendo let x =, tomando el valor original y agregando 1 para que el valor de x sea entonces 6. Luego, dentro de un ámbito interno creado con las llaves, la tercera declaración let también proyecta x y crea una nueva variable, multiplicando el valor anterior por 2 para darle a x un valor de 12. Cuando ese ámbito finaliza, la proyección interna finaliza y x vuelve a ser 6. Cuando ejecutamos este programa, se mostrará lo siguiente:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
The value of x in the inner scope is: 12
The value of x is: 6

El Shadowing es diferente de marcar una variable como mut porque obtendremos un error de tiempo de compilación si accidentalmente intentamos volver a asignar esta variable sin usar la palabra clave let. Al usar let, podemos realizar algunas transformaciones en un valor, pero la variable debe ser inmutable después de que se hayan completado esas transformaciones.

La otra diferencia entre mut y el shadowing es que, debido a que efectivamente estamos creando una nueva variable cuando usamos la palabra clave let nuevamente, podemos cambiar el tipo de valor pero reutilizar el mismo nombre. Por ejemplo, digamos que nuestro programa le pide al usuario que muestre cuántos espacios desea entre algún texto ingresando caracteres de espacio, y luego queremos almacenar esa entrada como un número:

fn main() {
    let spaces = "   ";
    let spaces = spaces.len();
}

La primera variable spaces es de tipo string y la segunda variable spaces es de tipo numérico. El shadowing nos ahorra tener que pensar en nombres diferentes, como spaces_str y spaces_num; en su lugar, podemos reutilizar el nombre más simple spaces. Sin embargo, si intentamos usar mut para esto, como se muestra aquí, obtendremos un error de tiempo de compilación:

fn main() {
    let mut spaces = "   ";
    spaces = spaces.len();
}

El error dice que no se permite mutar el tipo de una variable:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0308]: mismatched types
 --> src/main.rs:3:14
  |
2 |     let mut spaces = "   ";
  |                      ----- expected due to this value
3 |     spaces = spaces.len();
  |              ^^^^^^^^^^^^ expected `&str`, found `usize`

For more information about this error, try `rustc --explain E0308`.
error: could not compile `variables` (bin "variables") due to 1 previous error

Ahora que hemos explorado cómo funcionan las variables, veamos más tipos de datos que pueden tener.

Tipos de datos

Cada valor en Rust es de un cierto tipo de dato, que le dice a Rust qué tipo de dato se está especificando para que sepa cómo trabajar con ese dato. Veremos dos subconjuntos de tipos de datos: escalares y compuestos.

Tenga en cuenta que Rust es un lenguaje estáticamente tipado, lo que significa que debe conocer los tipos de todas las variables en tiempo de compilación. El compilador generalmente puede inferir qué tipo queremos usar en función del valor y cómo lo usamos. En los casos en que muchos tipos son posibles, como cuando convertimos un String en un tipo numérico usando parse en la sección “Comparando la Adivinanza con el Número Secreto” del capítulo 2, debemos agregar una anotación de tipo, como esta:

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Not a number!");
}

Si no agregamos la anotación de tipo : u32 mostrada en el código anterior, Rust mostrará el siguiente error, lo que significa que el compilador necesita más información de nosotros para saber qué tipo queremos usar:

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0284]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^        ----- type must be known at this point
  |
  = note: cannot satisfy `<_ as FromStr>::Err == _`
help: consider giving `guess` an explicit type
  |
2 |     let guess: /* Type */ = "42".parse().expect("Not a number!");
  |              ++++++++++++

For more information about this error, try `rustc --explain E0284`.
error: could not compile `no_type_annotations` (bin "no_type_annotations") due to 1 previous error

Verá diferentes anotaciones de tipo para otros tipos de datos.

Tipos Escalares

Un tipo escalar representa un solo valor. Rust tiene cuatro tipos escalares principales: enteros, números de punto flotante, booleanos y caracteres. Puede reconocerlos de otros lenguajes de programación. Vamos a ver cómo funcionan en Rust.

Tipos de Enteros

Un entero es un número sin componente fraccionario. Usamos un tipo de entero en el capítulo 2, el tipo u32. Esta declaración de tipo indica que el valor con el que está asociado debe ser un entero sin signo (los tipos de enteros con signo comienzan con i en lugar de u) que ocupa 32 bits de espacio. La tabla 3-1 muestra los tipos de enteros integrados en Rust. Podemos usar cualquiera de estas variantes para declarar el tipo de un valor entero.

Tabla 3-1: Tipos Enteros en Rust

Cada variante puede ser signed (con signo) o unsigned (sin signo) y tiene un tamaño explícito. Signed y unsigned se refieren a si es posible que el número sea negativo, es decir, si el número necesita tener un signo con él (signed) o si solo será positivo y por lo tanto puede representarse sin signo (unsigned). Es como escribir números en papel: cuando el signo importa, un número se muestra con un signo más o un signo menos; sin embargo, cuando es seguro suponer que el número es positivo, se muestra sin signo. Los números con signo se almacenan usando la representación de complemento a dos.

Cada variante con signo puede almacenar números de -(2^{n - 1}) a 2^{n - 1} - 1, donde n es el número de bits que usa la variante. Así, un i8 puede almacenar números de -(2⁷) a 2⁷ - 1, lo que equivale a -128 a 127. Las variantes sin signo pueden almacenar números de 0 a 2ⁿ - 1, por lo que un u8 puede almacenar números de 0 a 2⁸ - 1, lo que equivale a 0 a 255.

Además, los tipos isize y usize dependen de la arquitectura de la computadora en la que se ejecuta su programa, que se denota en la tabla como “arch”: 64 bits si está en una arquitectura de 64 bits y 32 bits si está en una arquitectura de 32 bits.

Puede escribir literales enteros en cualquiera de las formas que se muestran en la Tabla 3-2. Tenga en cuenta que los literales numéricos que pueden ser múltiples tipos numéricos permiten un sufijo de tipo, como 57u8, para designar el tipo. Los literales numéricos también pueden usar _ como un separador visual para facilitar la lectura del número, como 1_000, que tendrá el mismo valor que si hubiera especificado 1000.

Tabla 3-2: Literales enteros en Rust

Entonces, ¿cómo sabe qué tipo de entero usar? Si no está seguro, los valores predeterminados de Rust son generalmente buenos lugares para comenzar: los tipos enteros se configuran predeterminadamente en i32. La situación principal en la que usaría isize o usize es cuando indexa algún tipo de colección.

Desbordamiento de enteros

Digamos que tiene una variable de tipo u8 que puede contener valores entre 0 y 255. Si intenta cambiar la variable a un valor fuera de ese rango, como 256, se producirá un desbordamiento de enteros, que puede resultar en uno de dos comportamientos. Cuando está compilando en modo de depuración, Rust incluye comprobaciones para el desbordamiento de enteros que hacen que su programa se desborde en tiempo de ejecución si ocurre este comportamiento. Rust usa el término desbordamiento cuando un programa sale con un error; discutiremos los desbordamientos con más profundidad en la sección “Errores irrecuperables con panic!” del Capítulo 9.

Cuando está compilando en modo de lanzamiento con la bandera --release, Rust no incluye comprobaciones para el desbordamiento de enteros que provocan desbordamientos. En su lugar, si ocurre un desbordamiento, Rust realiza una envoltura de complemento a dos. En resumen, los valores mayores que el valor máximo que el tipo puede contener “se envuelven” al mínimo de los valores que el tipo puede contener. En el caso de un u8, el valor 256 se convierte en 0, el valor 257 se convierte en 1, y así sucesivamente. El programa no se desbordará, pero la variable tendrá un valor que probablemente no sea el que esperaba que tuviera. Depender del comportamiento de la envoltura del desbordamiento de enteros se considera un error.

Para manejar explícitamente la posibilidad de desbordamiento, puede usar estas familias de métodos proporcionados por la biblioteca estándar para tipos numéricos primitivos:

• Envolver en todos los modos con los métodos wrapping_*, como wrapping_add.
• Devolver el valor None si hay desbordamiento con los métodos checked_*.
• Devolver el valor y un booleano que indica si hubo desbordamiento con los métodos overflowing_*.
• Saturar en los valores mínimos o máximos del valor con los métodos saturating_*.

Tipos de punto flotante

Rust también tiene dos tipos primitivos para números de punto flotante, que son números con puntos decimales. Los tipos de punto flotante de Rust son f32 y f64, que tienen 32 bits y 64 bits de tamaño, respectivamente. El tipo predeterminado es f64 porque en CPUs modernas, es aproximadamente la misma velocidad que f32 pero es capaz de más precisión. Todos los tipos de punto flotante son con signo.

Aquí hay un ejemplo que muestra números de punto flotante en acción:

Nombre de archivo: src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

Los números de punto flotante se representan de acuerdo con el estándar IEEE-754. El tipo f32 es un punto flotante de precisión simple, y f64 tiene doble precisión.

Operaciones numéricas

Rust admite las operaciones matemáticas básicas que esperaría para todos los tipos de números: adición, sustracción, multiplicación, división y resto. La división entera se trunca hacia cero al entero más cercano. El siguiente código muestra cómo usaría cada operación numérica en una declaración let:

Nombre de archivo: src/main.rs

fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

    // division
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Results in -1

    // remainder
    let remainder = 43 % 5;
}

Cada expresión en estas instrucciones usa un operador matemático y se evalúa a un solo valor, que luego se vincula a una variable. El Apéndice B contiene una lista de todos los operadores que Rust proporciona.

El tipo booleano

Como en la mayoría de los otros lenguajes de programación, un tipo booleano en Rust tiene dos posibles valores: true y false. Los booleanos tienen un byte de tamaño. El tipo booleano en Rust se especifica usando bool. Por ejemplo:

Nombre de archivo: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // with explicit type annotation
}

La forma principal de usar valores booleanos es a través de condicionales, como una expresión if. Cubriremos cómo funcionan las expresiones if en Rust en la sección “Control de flujo”.

El tipo de carácter

El tipo char de Rust es el tipo alfabético más primitivo del lenguaje. Estos son algunos ejemplos de declaración de valores char:

Nombre de archivo: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // with explicit type annotation
    let heart_eyed_cat = '😻';
}

Tenga en cuenta que especificamos literales char con comillas simples, en oposición a literales de cadena, que usan comillas dobles. El tipo char de Rust tiene un tamaño de cuatro bytes y representa un valor escalar Unicode, lo que significa que puede representar mucho más que ASCII. Letras acentuadas; Caracteres chinos, japoneses y coreanos; Emojis; y espacios de ancho cero son todos valores char válidos en Rust. Los valores escalar de Unicode van desde U+0000 a U+D7FF y U+E000 a U+10FFFF inclusive. Sin embargo, un "carácter" no es realmente un concepto en Unicode, por lo que su intuición humana sobre lo que es un "carácter" puede no coincidir con lo que es un char en Rust. Discutiremos este tema en detalle en “Almacenar texto codificado en UTF-8 con cadenas” en el capítulo 8.

Tipos compuestos

Tipos compuestos pueden agrupar múltiples valores en un solo tipo. Rust tiene dos tipos compuestos primitivos: tuplas y arreglos.

El Tipo Tupla

Una tupla es una forma general de agrupar varios valores de distintos tipos en un tipo compuesto. Las tuplas tienen una longitud fija: una vez declaradas, su tamaño no puede aumentar ni disminuir.

Creamos una tupla escribiendo una lista de valores separados por comas dentro de paréntesis. Cada posición de la tupla tiene un tipo, y los tipos de los distintos valores de la tupla no tienen por qué ser iguales. En este ejemplo hemos añadido anotaciones de tipo opcionales:

Nombre de archivo: src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

La variable tup se vincula a toda la tupla porque una tupla se considera un único elemento compuesto. Para obtener los valores individuales de una tupla, podemos utilizar la concordancia de patrones para desestructurar un valor de tupla, así:

Nombre de archivo: src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("The value of y is: {y}");
}

Este programa primero crea una tupla y la vincula a la variable tup. Luego usa un patrón con let para tomar tup y convertirla en tres variables separadas, x, y y z. Esto se llama desestructuración porque rompe la única tupla en tres partes. Finalmente, el programa imprime el valor de y, que es 6.4.

También podemos acceder directamente a un elemento de la tupla usando un punto (.) seguido del índice del valor que queremos acceder. Por ejemplo:

Nombre de archivo: src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

Este programa crea la tupla x y luego accede a cada elemento de la tupla usando sus respectivos índices. Al igual que la mayoría de los lenguajes de programación, el primer índice en una tupla es 0.

La tupla sin ningún valor tiene un nombre especial, unit. Este valor y su tipo correspondiente están escritos ambos como () y representan un valor vacío o un tipo de retorno vacío. Las expresiones devuelven implícitamente el valor unit si no devuelven ningún otro valor.

El Tipo Arreglo

Otra forma de tener una colección de múltiples valores es con un arreglo. A diferencia de una tupla, cada elemento de un arreglo debe tener el mismo tipo. A diferencia de los arreglos en algunos otros lenguajes, los arreglos en Rust tienen una longitud fija.

Escribimos los valores en un arreglo como una lista separada por comas dentro de corchetes:

Nombre de archivo: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];
}

Los arreglos son útiles cuando desea que sus datos se asignen en el stack (pila) en lugar del heap (montículo) al igual que los otros tipos que hemos visto hasta ahora (hablaremos más sobre el stack y el heap en el Capítulo 4) o cuando desea asegurarse de que siempre tenga un número fijo de elementos. Sin embargo, un arreglo no es tan flexible como el tipo vector. Un vector es un tipo de colección similar proporcionado por la biblioteca estándar que puede crecer o reducir su tamaño. Si no está seguro de si debe usar un arreglo o un vector, es probable que deba usar un vector. El Capítulo 8 discute los vectores en más detalle.

Sin embargo, los arreglos son más útiles cuando sabe que el número de elementos no cambiará. Por ejemplo, si está utilizando los nombres del mes en un programa, probablemente usaría un arreglo en lugar de un vector porque sabe que siempre contendrá 12 elementos:

#![allow(unused)]
fn main() {
let months = ["January", "February", "March", "April", "May", "June", "July",
              "August", "September", "October", "November", "December"];
}

Escribe el tipo de un arreglo usando corchetes con el tipo de cada elemento, un punto y coma y luego el número de elementos en el arreglo, así:

#![allow(unused)]
fn main() {
let a: [i32; 5] = [1, 2, 3, 4, 5];
}

Aquí, i32 es el tipo de cada elemento. Después del punto y coma, el número 5 indica que el arreglo contiene cinco elementos.

También puede inicializar un arreglo para contener el mismo valor para cada elemento especificando el valor inicial, seguido de un punto y coma y luego la longitud del arreglo en corchetes, como se muestra aquí:

#![allow(unused)]
fn main() {
let a = [3; 5];
}

El arreglo llamado a contendrá 5 elementos que inicialmente se establecerán en el valor 3. Esto es lo mismo que escribir let a = [3, 3, 3, 3, 3]; pero de una manera más concisa.

Accediendo a los Elementos del Arreglo

Un arreglo es un trozo de memoria de tamaño fijo y conocido que puede asignarse a la pila. Se puede acceder a los elementos de una arreglo utilizando la indexación, de la siguiente manera:

Nombre de archivo: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}

En este ejemplo, la variable llamada first obtendrá el valor 1 porque ese es el valor en el índice [0] en el arreglo. La variable llamada second obtendrá el valor 2 del índice [1] en el arreglo.

Acceso Inválido a los Elementos del Arreglo

Veamos qué sucede si intenta acceder a un elemento de un arreglo que está más allá del final del arreglo. Digamos que ejecuta este código, similar al juego de adivinanzas del Capítulo 2, para obtener un índice de arreglo del usuario:

Nombre de archivo: src/main.rs

use std::io;

fn main() {
    let a = [1, 2, 3, 4, 5];

    println!("Please enter an array index.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Failed to read line");

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

    let element = a[index];

    println!("The value of the element at index {index} is: {element}");
}

Este código se compila con éxito. Si ejecuta este código usando cargo run y ingresa 0, 1, 2, 3 o 4, el programa imprimirá el valor correspondiente en ese índice en el arreglo. Si en cambio ingresa un número más allá del final del arreglo, como 10, verá una salida como esta:

thread 'main' panicked at src/main.rs:19:19:
index out of bounds: the len is 5 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

El programa dio lugar a un error en tiempo de ejecución al momento de utilizar un valor no válido en la operación de indexación. El programa salió con un mensaje de error y no ejecutó la sentencia final println!. Cuando intentas acceder a un elemento utilizando la indexación, Rust comprobará que el índice que has especificado es menor que la longitud del array. Si el índice es mayor o igual que la longitud, Rust entrará en pánico. Esta comprobación tiene que ocurrir en tiempo de ejecución, especialmente en este caso, porque el compilador no puede saber qué valor introducirá el usuario cuando ejecute el código más tarde.

Este es un ejemplo de los principios de seguridad de memoria de Rust en acción. En muchos lenguajes de bajo nivel, este tipo de comprobación no se hace, y cuando proporcionas un índice incorrecto, se puede acceder a memoria inválida. Rust te protege contra este tipo de error saliendo inmediatamente en lugar de permitir el acceso a la memoria y continuar. El Capítulo 9 discute más sobre el manejo de errores de Rust y cómo puedes escribir código legible y seguro que no entre en pánico ni permita el acceso a memoria inválida.

Funciones

Las Funciones son muy comunes en el código Rust. Ya has visto una de las funciones más importantes del lenguaje: la función main, que es el punto de entrada de muchos programas. También has visto la palabra clave fn, que te permite declarar nuevas funciones.

El código en Rust usa snake case como estilo convencional para los nombres de funciones y variables, en el que todas las letras son minúsculas y los guiones bajos separan las palabras. Aquí hay un programa que contiene un ejemplo de definición de una función:

Nombre de archivo: src/main.rs

fn main() {
    println!("Hello, world!");

    another_function();
}

fn another_function() {
    println!("Another function.");
}

Definimos una función en Rust escribiendo fn seguido del nombre de la función y un conjunto de paréntesis. Las llaves indican al compilador donde comienza y termina el cuerpo de la función.

Podemos llamar a cualquier función que hayamos definido escribiendo su nombre seguido de un conjunto de paréntesis. Como another_function está definida en el programa, se puede llamar desde dentro de la función main. Ten en cuenta que definimos another_function después de la función main en el código fuente; también podríamos haberla definido antes. A Rust no le importa dónde definas tus funciones, sólo que estén definidas en algún lugar en un ámbito que pueda ser visto por el invocador.

Empecemos un nuevo proyecto binario llamado functions para explorar las funciones más a fondo. Coloca el ejemplo de another_function en src/main.rs y ejecútalo. Deberías ver la siguiente salida:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.28s
     Running `target/debug/functions`
Hello, world!
Another function.

Las líneas se ejecutan en el orden en que aparecen en la función main. Primero se imprime el mensaje “Hello, world!”, y luego se llama a another_function y se imprime su mensaje.

Parámetros

Podemos definir funciones para que tengan parámetros, que son variables especiales que forman parte de la firma de una función. Cuando una función tiene parámetros, puedes proporcionarle valores concretos para esos parámetros. Técnicamente, los valores concretos se llaman argumentos, pero coloquialmente, la gente tiende a usar las palabras parámetro y argumento indistintamente para las variables en la definición de una función o los valores concretos que se pasan cuando llamas a una función.

En esta versión de another_function agregamos un parámetro:

Nombre de archivo: src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("The value of x is: {x}");
}

Intenta ejecutar este programa; deberías obtener la siguiente salida:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
The value of x is: 5

La declaración de another_function tiene un parámetro llamado x. El tipo de x se especifica como i32. Cuando pasamos 5 a another_function, la macro println! pone 5 donde estaba el par de llaves que contenía x en la cadena de formato.

En las firmas de las funciones, debes declarar el tipo de cada parámetro. Esta es una decisión deliberada en el diseño de Rust: requerir anotaciones de tipo en las definiciones de las funciones significa que el compilador casi nunca necesita que las uses en otro lugar del código para averiguar a qué tipo te refieres. El compilador también puede dar mensajes de error más útiles si sabe qué tipos espera la función.

Al definir múltiples parámetros, separa las declaraciones de parámetros con comas, como esto:

Nombre de archivo: src/main.rs

fn main() {
    print_labeled_measurement(5, 'h');
}

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("The measurement is: {value}{unit_label}");
}

Este ejemplo crea una función llamada print_labeled_measurement con dos parámetros. El primer parámetro se llama value y es un i32. El segundo parámetro se llama unit_label y es de tipo char. Luego, la función imprime texto que contiene tanto el value como el unit_label.

Intentemos ejecutar este código. Reemplaza el programa actual en tu proyecto functions en el archivo src/main.rs con el ejemplo anterior y ejecútalo usando cargo run:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/functions`
The measurement is: 5h

Como hemos llamamos a la función con 5 como valor para value y 'h' como valor para unit_label, la salida del programa contiene esos valores.

Sentencias y Expresiones

Los cuerpos de las funciones están compuestos por una serie de sentencias opcionalmente terminadas en una expresión. Hasta ahora, las funciones que hemos visto no incluyen una expresión final, pero has visto una expresión como parte de una sentencia. Debido a que Rust es un lenguaje basado en expresiones, esta es una distinción importante de entender. Otros lenguajes no tienen las mismas distinciones, así que veamos qué son las sentencias y las expresiones y cómo sus diferencias afectan a los cuerpos de las funciones.

• Sentencias son instrucciones que realizan alguna acción y no devuelven un valor.
• Expresiones evalúan a un valor resultante. Veamos algunos ejemplos.

Hemos usado realmente sentencias y expresiones. Crear una variable y asignarle un valor con la palabra clave let es una sentencia. En el Listado 3-1, let y = 6; es una sentencia.

fn main() {
    let y = 6;
}

Las definiciones de las funciones también son sentencias; todo el ejemplo anterior es una sentencia en sí misma. (Como veremos a continuación, ejecutar una función no es una sentencia.)

Las sentencias no devuelven valores. Por lo tanto, no puedes asignar una sentencia let a otra variable, como intenta hacer el siguiente código; obtendrás un error:

Nombre de archivo: src/main.rs

fn main() {
    let x = (let y = 6);
}

Cuando ejecutes este programa, el error que obtendrás se verá así:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^
  |
  = note: only supported directly in conditions of `if` and `while` expressions

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` (bin "functions") due to 1 previous error; 1 warning emitted

La sentencia let y = 6 no devuelve un valor, por lo que no hay nada a lo que x se pueda vincular. Esto es diferente a lo que ocurre en otros lenguajes, como C y Ruby, donde la asignación devuelve el valor de la asignación. En esos lenguajes, puedes escribir x = y = 6 y hacer que tanto x como y tengan el valor 6; eso no es el caso en Rust.

Las expresiones evalúan a un valor y componen la mayor parte del resto del código que escribirás en Rust. Considera una operación matemática, como 5 + 6, que es una expresión que evalúa al valor 11. Las expresiones pueden ser parte de las sentencias: en el Listado 3-1, el 6 en la sentencia let y = 6; es una expresión que evalúa al valor 6. Llamar a una función es una expresión. Llamar a una macro es una expresión. Un nuevo bloque de ámbito creado con llaves es una expresión, por ejemplo:

Nombre de archivo: src/main.rs

fn main() {
    let y = {
        let x = 3;
        x + 1
    };

    println!("The value of y is: {y}");
}

Esta expresión:

{
    let x = 3;
    x + 1
}

es un bloque que, en este caso, evalúa a 4. Ese valor se enlaza a y como parte de la sentencia let. Ten en cuenta que la línea x + 1 no tiene un punto y coma al final, lo que es diferente a la mayoría de las líneas que has visto hasta ahora. Las expresiones no incluyen punto y coma al final. Si agregas un punto y coma al final de una expresión, la conviertes en una sentencia, y entonces no devolverá un valor. Ten esto en cuenta a medida que exploras los valores de retorno de las funciones y las expresiones a continuación.

Funciones con valores de retorno

Las funciones pueden devolver valores al código que las llama. No nombramos los valores de retorno, pero debemos declarar su tipo después de una flecha (->). En Rust, el valor de retorno de la función es sinónimo del valor de la última expresión en el bloque del cuerpo de una función. Puedes devolver un valor antes de que la función finalice utilizando la palabra clavereturn y especificando un valor, pero la mayoría de las funciones devuelven la última expresión implícitamente. Aquí hay un ejemplo de una función que devuelve un valor:

Nombre de archivo: src/main.rs

fn five() -> i32 {
    5
}

fn main() {
    let x = five();

    println!("The value of x is: {x}");
}

No hay llamadas a funciones, macros, ni siquiera sentencias let en la función five - solo el número 5 por sí solo. Esa es una función perfectamente válida en Rust. Ten en cuenta que también se especifica el tipo de retorno de la función, como -> i32. Intenta ejecutar este código; la salida debería verse así:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
The value of x is: 5

El 5 en five es el valor de retorno de la función, por eso el tipo de retorno es i32. Veamos esto con más detalle. Hay dos partes importantes: primero, la línea let x = five(); muestra que estamos usando el valor de retorno de una función para inicializar una variable. Debido a que la función five devuelve un 5, esa línea es la misma que la siguiente:

#![allow(unused)]
fn main() {
let x = 5;
}

Segundo, la función five no tiene parámetros y define el tipo del valor de retorno, pero el cuerpo de la función es un solitario 5 sin punto y coma porque es una expresión cuyo valor queremos devolver.

Veamos otro ejemplo:

Nombre de archivo: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1
}

La ejecución de este código imprimirá The value of x is: 6. Pero si colocamos un punto y coma al final de la línea que contiene x + 1, cambiándolo de una expresión a una sentencia, obtendremos un error:

Nombre de archivo: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1;
}

La compilación de este código produce un error, como sigue:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error[E0308]: mismatched types
 --> src/main.rs:7:24
  |
7 | fn plus_one(x: i32) -> i32 {
  |    --------            ^^^ expected `i32`, found `()`
  |    |
  |    implicitly returns `()` as its body has no tail or `return` expression
8 |     x + 1;
  |          - help: remove this semicolon to return this value

For more information about this error, try `rustc --explain E0308`.
error: could not compile `functions` (bin "functions") due to 1 previous error

El mensaje de error principal, mismatched types, revela el problema principal con este código. La definición de la función plus_one dice que devolverá un i32, pero las sentencias no evalúan un valor, lo que se expresa por (), el tipo unitario. Por lo tanto, no se devuelve nada, lo que contradice la definición de la función y da como resultado un error. En esta salida, Rust proporciona un mensaje para posiblemente ayudar a corregir este problema: sugiere eliminar el punto y coma, lo que arreglaría el error.

Comentarios

Todos los programadores se esfuerzan por hacer que su código sea fácil de entender, pero a veces se requiere una explicación adicional. En estos casos, los programadores dejan comentarios en su código fuente que el compilador ignorará pero que las personas que lean el código fuente pueden encontrar útiles.

Aquí hay un comentario simple:

#![allow(unused)]
fn main() {
// hola, mundo
}

En Rust, el estilo de comentario idiomático comienza un comentario con dos barras inclinadas y el comentario continúa hasta el final de la línea. Para comentarios que se extienden más allá de una sola línea, deberá incluir // en cada línea, así:

#![allow(unused)]
fn main() {
// Así que estamos haciendo algo complicado aquí, lo suficientemente largo
// como para necesitar varias líneas de comentarios para hacerlo. ¡Uf!
// ¡Espero que este comentario explique lo que está sucediendo!
}

Los comentarios también se pueden colocar al final de las líneas que contienen código:

Nombre de archivo: src/main.rs

fn main() {
    let numero_de_la_suerte = 7; // Me siento afortunado hoy
}

Pero más a menudo verás que se usan en este formato, con el comentario en una línea separada por encima del código que está anotando:

Nombre de archivo: src/main.rs

fn main() {
    // Me siento afortunado hoy
    let numero_de_la_suerte = 7;
}

Rust también tiene otro tipo de comentario, comentarios de documentación, que discutiremos en la sección “Publicando una Caja en Crates.io” del Capítulo 14.

Flujo de Control

La capacidad de ejecutar algún código dependiendo de si una condición es true y ejecutar algún código repetidamente mientras una condición es true son elementos básicos en la mayoría de los lenguajes de programación. Las construcciones más comunes que le permiten controlar el flujo de ejecución del código Rust son las expresiones if y los bucles.

Expresiones if

Una expresión if le permite dividir su código según las condiciones. Proporciona una condición y luego dice: “Si se cumple esta condición, ejecute este bloque de código. Si la condición no se cumple, no ejecute este bloque de código.”

Cree un nuevo proyecto llamado branches en su directorio projects para explorar la expresión if. En el archivo src/main.rs, ingrese lo siguiente:

Nombre de archivo: src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

Todas las expresiones if comienzan con la palabra clave if, seguida de una condición. En este caso, la condición comprueba si la variable number tiene un valor menor que 5. Colocamos el bloque de código para ejecutar si la condición es true inmediatamente después de la condición dentro de llaves. Los bloques de código asociados con las condiciones en las expresiones if a veces se llaman brazos, al igual que los brazos en las expresiones match que discutimos en la sección “Comparando la Adivinanza con el Número Secreto” del Capítulo 2.

Opcionalmente, también podemos incluir una expresión else, que elegimos hacer aquí, para dar al programa un bloque de código alternativo para ejecutar si la condición evaluada es false. Si no proporciona una expresión else y la condición es false, el programa va a ignorar el bloque if y continuará con el siguiente fragmento de código.

Intente ejecutar este código; Debería ver la siguiente salida:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was true

Vamos a intentar cambiar el valor de number a un valor que haga que la condición sea false para ver qué sucede:

fn main() {
    let number = 7;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

Ejecute el programa nuevamente y observe la salida:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was false

También vale la pena señalar que la condición en este código debe ser un bool. Si la condición no es un bool, obtendremos un error. Por ejemplo, intente ejecutar el siguiente código:

Nombre de archivo: src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("number was three");
    }
}

La condición if se evalúa como un valor de 3 esta vez, y Rust arroja un error:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: mismatched types
 --> src/main.rs:4:8
  |
4 |     if number {
  |        ^^^^^^ expected `bool`, found integer

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

El error indica que Rust esperaba un bool pero obtuvo un entero. A diferencia de los lenguajes como Ruby y JavaScript, Rust no intentará convertir automáticamente los tipos no booleanos en un booleano. Debes ser explícito y siempre proporcionar a if un booleano como su condición. Si queremos que el bloque de código if se ejecute solo cuando un número no sea igual a 0, por ejemplo, podemos cambiar la expresión if a lo siguiente:

Nombre de archivo: src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number was something other than zero");
    }
}

Ejecutando este código imprimirá number was something other than zero.

Manejo de múltiples condiciones con else if

Puede usar múltiples condiciones combinando if y else en una expresión else if. Por ejemplo:

Nombre de archivo: src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("number is divisible by 4");
    } else if number % 3 == 0 {
        println!("number is divisible by 3");
    } else if number % 2 == 0 {
        println!("number is divisible by 2");
    } else {
        println!("number is not divisible by 4, 3, or 2");
    }
}

Este programa tiene cuatro posibles caminos que puede tomar. Después de ejecutarlo, debería ver la siguiente salida:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
number is divisible by 3

Cuando se ejecuta este programa, verifica cada expresión if en orden y ejecuta el primer cuerpo para el cual la condición se evalúa como true. Tenga en cuenta que incluso si 6 es divisible por 2, no vemos la salida number is divisible by 2, ni vemos el texto number is not divisible by 4, 3, or 2 del bloque else. Esto se debe a que Rust solo ejecuta el bloque para la primera condición true, y una vez que encuentra una, ni siquiera verifica el resto.

El uso de demasiadas expresiones else if puede ensuciar su código, por lo que si tiene más de una, es posible que desee refactorizar su código. El capítulo 6 describe una poderosa construcción de ramificación de Rust llamada match para estos casos.

Usando if en una declaración let

Dado que if es una expresión, podemos usarlo en el lado derecho de una declaración let para asignar el resultado a una variable, como en el Listado 3-2.

fn main() {
    let condition = true;
    let number = if condition { 5 } else { 6 };

    println!("The value of number is: {number}");
}

La variable number estará vinculada a un valor basado en el resultado de la expresión if. Ejecute este código para ver qué sucede:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
The value of number is: 5

Recuerde que los bloques de código se evalúan en la última expresión de ellos y los números por sí mismos también son expresiones. En este caso, el valor de la expresión if en su conjunto depende de qué bloque de código se ejecuta. Esto significa que los valores que tienen el potencial de ser resultados de cada rama del if deben ser del mismo tipo; en el Listado 3-2, los resultados de ambas ramas del if y la rama else fueron enteros i32. Si los tipos no coinciden, como en el siguiente ejemplo, obtendremos un error:

Nombre de archivo: src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "six" };

    println!("The value of number is: {number}");
}

Cuando intentamos compilar este código, obtendremos un error. Las ramas if y else tienen tipos de valor que son incompatibles, y Rust indica exactamente dónde encontrar el problema en el programa:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: `if` and `else` have incompatible types
 --> src/main.rs:4:44
  |
4 |     let number = if condition { 5 } else { "six" };
  |                                 -          ^^^^^ expected integer, found `&str`
  |                                 |
  |                                 expected because of this

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

La expresión en el bloque if se evalúa como un entero, y la expresión en el bloque else se evalúa como una cadena. Esto no funcionará porque las variables deben tener un solo tipo, y Rust necesita saber en tiempo de compilación qué tipo tiene la variable number, definitivamente. Conocer el tipo de number permite al compilador verificar que el tipo sea válido en cualquier lugar que usemos number. Rust no podría hacerlo si el tipo de number solo se determinara en tiempo de ejecución; el compilador sería más complejo y haría menos garantías sobre el código si tuviera que rastrear diversos tipos hipotéticos para cualquier variable.

Repetición con bucles

A menudo es útil ejecutar un bloque de código más de una vez. Para esta tarea, Rust proporciona varios bucles, que ejecutarán el código dentro del cuerpo del bucle hasta el final y luego comenzarán de inmediato desde el principio. Para experimentar con los bucles, hagamos un nuevo proyecto llamado loops.

Rust tiene tres tipos de bucles: loop, while y for. Vamos a probar cada uno.

Repetir código con loop

La palabra clave loop le dice a Rust que ejecute un bloque de código una y otra vez para siempre o hasta que le indique explícitamente que se detenga.

Como ejemplo, cambie el archivo src/main.rs en su directorio loops para que se vea así:

Nombre de archivo: src/main.rs

fn main() {
    loop {
        println!("again!");
    }
}

Cuando ejecutemos este programa, veremos again! impreso una y otra vez continuamente hasta que detengamos manualmente el programa. La mayoría de los terminales admiten el atajo de teclado ctrl-c para interrumpir un programa que está atascado en un bucle continuo. Inténtelo:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/loops`
again!
again!
again!
again!
^Cagain!

El símbolo ^C representa dónde presionó ctrl-c. Puede que vea o no la palabra again! impresa después del ^C, dependiendo de dónde estaba el código en el bucle cuando recibió la señal de interrupción.

Afortunadamente, Rust también proporciona una forma de salir de un bucle utilizando código. Puede colocar la palabra clave break dentro del bucle para decirle al programa cuándo dejar de ejecutar el bucle. Recuerde que hicimos esto en el juego de adivinanzas en la sección “Salir después de una adivinanza correcta” del capítulo 2 para salir del programa cuando el usuario ganó el juego adivinando el número correcto.

También usamos continue en el juego de adivinanzas, que en un bucle le dice al programa que omita cualquier código restante en esta iteración del bucle y pase a la siguiente iteración.

Devolviendo valores de los bucles

Una de las aplicaciones de un loop es volver a intentar una operación que sabe que puede fallar, como verificar si un hilo ha completado su trabajo. Es posible que también necesite pasar el resultado de esa operación fuera del bucle al resto de su código. Para hacer esto, puede agregar el valor que desea devolver después de la expresión break que usa para detener el bucle; ese valor se devolverá fuera del bucle para que pueda usarlo, como se muestra aquí:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
        }
    };

    println!("The result is {result}");
}

Antes del bucle, declaramos una variable llamada counter e inicializamos en 0. Luego declaramos una variable llamada result para contener el valor devuelto del bucle. En cada iteración del bucle, agregamos 1 a la variable counter, y luego verificamos si el counter es igual a 10. Cuando lo es, usamos la palabra clave break con el valor counter * 2. Después del bucle, usamos un punto y coma para terminar la instrucción que asigna el valor a result. Finalmente, imprimimos el valor en result, que en este caso es 20.

Tu puedes también usar return dentro de un loop. Mientras break solo existe para el loop actual, return siempre existe para la función actual.

Etiquetas de bucle para distinguir entre varios bucles

Si tiene bucles dentro de bucles, break y continue se aplican al bucle más interior en ese punto. Opcionalmente, puede especificar una etiqueta de bucle en un bucle que luego puede usar con break o continue para especificar que esas palabras clave se aplican al bucle etiquetado en lugar del bucle más interior. Las etiquetas de bucle deben comenzar con una comilla simple. Aquí hay un ejemplo con dos bucles anidados:

fn main() {
    let mut count = 0;
    'counting_up: loop {
        println!("count = {count}");
        let mut remaining = 10;

        loop {
            println!("remaining = {remaining}");
            if remaining == 9 {
                break;
            }
            if count == 2 {
                break 'counting_up;
            }
            remaining -= 1;
        }

        count += 1;
    }
    println!("End count = {count}");
}

El bucle externo tiene la etiqueta 'counting_up, y contará de 0 a 2. El bucle interior sin etiqueta cuenta de 10 a 9. El primer break que no especifique una etiqueta solo saldrá del bucle interno. La instrucción break 'counting_up; saldrá del bucle externo. Este código imprime:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
count = 0
remaining = 10
remaining = 9
count = 1
remaining = 10
remaining = 9
count = 2
remaining = 10
End count = 2

Bucles condicionales con while

Un programa a menudo necesitará evaluar una condición dentro de un bucle. Mientras la condición sea true, el bucle se ejecuta. Cuando la condición deja de ser true, el programa llama a break, deteniendo el bucle. Es posible implementar un comportamiento como este usando una combinación de loop, if, else y break; puede intentarlo ahora en un programa, si lo desea. Sin embargo, este patrón es tan común que Rust tiene una construcción de lenguaje integrada para ello, llamada while loop. En el Listado 3-3, usamos while para ejecutar el programa tres veces, contando hacia atrás cada vez, y luego, después del bucle, imprimir un mensaje y salir.

fn main() {
    let mut number = 3;

    while number != 0 {
        println!("{number}!");

        number -= 1;
    }

    println!("LIFTOFF!!!");
}

Esta expresion elimina mucho anidamiento que sería necesario si usara loop, if, else y break, y es más claro. Mientras una condición se evalúa como true, el código se ejecuta; de lo contrario, sale del bucle.

Bucle a traves de una colección con for

Tu puedes también puedes usar el while para recorrer los elementos de una colección, justo como un arreglo. Por ejemplo, el bucle en el Listado 3-4 muestra cada elemento en el arreglo a.

fn main() {
    let a = [10, 20, 30, 40, 50];
    let mut index = 0;

    while index < 5 {
        println!("the value is: {}", a[index]);

        index += 1;
    }
}

Aquí, el código cuenta hacia arriba a través de los elementos en el arreglo. Se inicia en el índice 0, y luego se ejecuta hasta que alcanza el índice final en el arreglo (es decir, cuando index < 5 ya no es true). Ejecutar este código imprimirá cada elemento en el arreglo:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
the value is: 10
the value is: 20
the value is: 30
the value is: 40
the value is: 50

Los cinco valores del arreglo aparecen en la terminal, como se esperaba. Aunque index llegará a un valor de 5 en algún momento, el bucle deja de ejecutarse antes de intentar obtener un sexto valor del arreglo.

Sin embargo, este enfoque es propenso a errores; podríamos causar que el programa se descomponga si el valor del índice o la condición de prueba es incorrecta. Por ejemplo, si cambia la definición del arreglo a para tener cuatro elementos, pero olvida actualizar la condición a while index < 4, el código se descompondría. También es lento, porque el compilador agrega código de tiempo de ejecución para realizar la verificación condicional de si el índice está dentro de los límites del arreglo en cada iteración del bucle.

Como una alternativa más concisa, puede usar un bucle for y ejecutar algún código para cada elemento en una colección. Un bucle for se ve como el código en el Listado 3-5.

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }
}

Cuando ejecutamos este código, veremos la misma salida que en el Listado 3-4. Lo más importante es que ahora hemos aumentado la seguridad del código y eliminado la posibilidad de errores que podrían deberse a ir más allá del final del arreglo o no ir lo suficientemente lejos y perder algunos elementos.

Usando el bucle for, no necesitaría recordar cambiar cualquier otro código si cambiara el número de valores en el arreglo, como lo haría con el método usado en el Listado 3-4.

La seguridad y concisión de los bucles for los convierten en la estructura de bucle más utilizada en Rust. Incluso en situaciones en las que quiera ejecutar algún código un cierto número de veces, como en el ejemplo de cuenta regresiva que usó un bucle while en el Listado 3-3, la mayoría de los Rustaceans usarían un bucle for. La forma de hacerlo sería usar un Range, proporcionado por la biblioteca estándar, que genera todos los números en secuencia a partir de un número y termina antes de otro número.

Así es como se vería la cuenta regresiva usando un bucle for y otro método que aún no hemos hablado, rev, para invertir el rango:

Nombre de archivo: src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("LIFTOFF!!!");
}

Este código es un poco más agradable, ¿verdad?

Resumen

¡Lo lograste! Este fue un capítulo de gran tamaño: aprendiste sobre variables, tipos de datos escalares y compuestos, funciones, comentarios, expresiones if y bucles. Para practicar con los conceptos discutidos en este capítulo, intente construir programas para hacer lo siguiente:

• Convertir temperaturas entre Fahrenheit y Celsius.
• Generar el número de Fibonacci n.
• Imprimir las letras de la canción navideña "Los doce días de Navidad", aprovechando la repetición en la canción.

Cuando esté listo para continuar, hablaremos sobre un concepto en Rust que no existe comúnmente en otros lenguajes de programación: la propiedad.

Entendiendo el Ownership

El Ownership es la característica más única de Rust y tiene implicaciones profundas para el resto del lenguaje. Permite a Rust hacer garantías de seguridad de memoria sin necesidad de un recolector de basura, por lo que es importante entender cómo funciona el Ownership. En este capítulo, hablaremos sobre el Ownership así como varias características relacionadas: préstamo (borrowing), slices, y cómo Rust organiza los datos en la memoria.

¿Qué es el Ownership?

El ownership es un conjunto de reglas que definen cómo un programa de Rust administra la memoria. Todos los programas tienen que administrar la forma en que usan la memoria de un computador mientras se ejecutan. Algunos lenguajes tienen recolección de basura que busca regularmente la memoria que ya no se usa mientras el programa se ejecuta; en otros lenguajes, el programador debe asignar y liberar la memoria explícitamente. Rust usa un tercer enfoque: la memoria se administra a través de un sistema de ownership con un conjunto de reglas que el compilador verifica. Si alguna de las reglas se viola, el programa no se compilará. Ninguna de las características del ownership ralentizará su programa mientras se ejecuta.

Porque el ownership es un concepto nuevo para muchos programadores, toma un tiempo acostumbrarse. La buena noticia es que a medida que se vuelva más experimentado con Rust y las reglas del sistema de ownership, más fácil le resultará desarrollar naturalmente código que sea seguro y eficiente. ¡Sigue intentándolo!

Cuando entienda el ownership, tendrá una base sólida para comprender las características que hacen que Rust sea único. En este capítulo, aprenderá ownership trabajando en algunos ejemplos que se centran en una estructura de datos muy común: las cadenas de caracteres.

Nota: La traducción de Ownership seria "Propiedad", la mayor parte de la comunidad habla de este sistema como Ownsership pero también es valido este termino. El motivo es que el sistema de ownership es solo una analogía.

La analogía es que el ownership es como la propiedad de un objeto, por ejemplo si tienes un libro, el libro es tuyo. Si lo prestas a alguien, el libro sigue siendo tuyo, pero ahora el libro esta en posesión de otra persona. Cuando te devuelven el libro, el libro regresa a tu posesión.

El Stack y el Heap

Muchos lenguajes de programación no requieren que piense mucho en el stack y el heap. Pero en un lenguaje de programación de sistemas como Rust, si un valor está en el stack o en el heap afecta cómo el lenguaje se comporta y por qué debe tomar ciertas decisiones. Partes del ownership se describirán en relación con el stack y el heap más adelante en este capítulo, por lo que aquí hay una breve explicación en preparación.

Tanto el stack como el heap son partes de la memoria disponible para su código para usar en tiempo de ejecución, pero están estructurados de formas diferentes. El stack almacena valores en el orden en que los recibe y elimina los valores en el orden opuesto. Esto se conoce como LIFO que es el acrónimo inglés de Last In, First Out o en español El último en entrar, es el primero en salir. Piense en una pila de platos: cuando agrega más platos, los coloca en la parte superior de la pila, y cuando necesita un plato, toma uno de la parte superior. Agregar o eliminar platos del medio o de la parte inferior no funcionaría tan bien! Agregar datos se llama empujar en el stack, y eliminar datos se llama sacar del stack. Todos los datos almacenados en el stack deben tener un tamaño conocido y fijo. Los datos con un tamaño desconocido en tiempo de compilación o un tamaño que puede cambiar deben almacenarse en el heap en su lugar.

El heap es menos organizado: cuando coloca datos en el heap, solicita una cierta cantidad de espacio. El administrador de memoria encuentra un lugar vacío en el heap que sea lo suficientemente grande, lo marca como en uso y devuelve un puntero, que es la dirección de esa ubicación. Este proceso se llama asignar en el heap y a veces se abrevia como solo asignar (empujar valores en el stack no se considera asignar). Debido a que el puntero al heap es un tamaño conocido y fijo, puede almacenar el puntero en el stack, pero cuando desea los datos reales, debe seguir el puntero. Piense en estar sentado en un restaurante. Cuando ingresa, indica la cantidad de personas en su grupo, y el anfitrión encuentra una mesa vacía que quepa a todos y los lleva allí. Si alguien en su grupo llega tarde, puede preguntar dónde se ha sentado para encontrarlo.

Empujar en el stack es más rápido que asignar en el heap porque el administrador de memoria nunca tiene que buscar un lugar para almacenar nuevos datos; esa ubicación siempre está en la parte superior de la pila. En comparación, asignar espacio en el heap requiere más trabajo porque el administrador de memoria debe encontrar primero un espacio lo suficientemente grande para contener los datos y luego realizar tareas administrativas para prepararse para la siguiente asignación.

Acceder a los datos en el heap es más lento que acceder a los datos en el stack porque debe seguir un puntero para llegar allí. Los procesadores contemporáneos son más rápidos si saltan menos en la memoria. Continuando con la analogía, considere un servidor en un restaurante que toma pedidos de muchas mesas. Es más eficiente obtener todos los pedidos de una mesa antes de pasar a la siguiente mesa. Tomar un pedido de la mesa A, luego un pedido de la mesa B, luego uno de la A nuevamente y luego uno de la B nuevamente sería un proceso mucho más lento. Del mismo modo, un procesador puede hacer su trabajo mejor si trabaja con datos que están cerca de otros datos (como lo están en el stack) en lugar de más lejos (como pueden estar en el heap).

Cuando su código llama a una función, los valores que se pasan a la función (incluidos, posiblemente, punteros a datos en el heap) y las variables locales de la función se empujan en el stack. Cuando la función termina, esos valores se sacan del stack.

Mantener un registro de qué partes del código están utilizando qué datos en el heap, minimizar la cantidad de datos duplicados en el heap y limpiar los datos no utilizados en el heap para que no se quede sin espacio son todos problemas que ownership aborda. Una vez que comprenda ownership, no tendrá que pensar mucho en el stack y el heap, pero saber que el principal propósito de ownership es administrar datos en el heap puede ayudar a explicar por qué funciona de la manera en que lo hace.

Reglas de Ownership

Primero, echemos un vistazo a las reglas de ownership. Mantenga estas reglas en mente mientras trabajamos a través de los ejemplos que las ilustran:

• Cada valor en Rust tiene un propietario.
• Solo puede haber un propietario a la vez.
• Cuando el propietario sale del alcance, el valor se descartará.

Ámbito de las Variables

Ahora que hemos pasado la sintaxis básica de Rust, no incluiremos todo el código fn main() { en los ejemplos, por lo que si está siguiendo, asegúrese de colocar los siguientes ejemplos dentro de una función main manualmente. Como resultado, nuestros ejemplos serán un poco más concisos, permitiéndonos centrarnos en los detalles reales en lugar del código repetitivo.

Como primer ejemplo de ownership, veremos el contexto de ejecución de algunas variables. Un contexto de ejecución es el rango o espacio dentro de un programa para el que un elemento es válido. Toma la siguiente variable:

#![allow(unused)]
fn main() {
let s = "hola";
}

La variable s se refiere a un literal de cadena, donde el valor de la cadena está codificado en el texto de nuestro programa. La variable es válida desde el punto en que se declara hasta el final del contexto de ejecución actual. El listado 4-1 muestra un programa con comentarios que anotan dónde sería válida la variable s.

fn main() {
    {                      // s no es valido aquí, aún no está declarado
        let s = "hola";   // s es valido desde aquí

        // Hacer algo con s
    }                      // este ámbito termina aquí, s ya no es valido
}

En otras palabras, hay dos puntos importantes en el tiempo aquí:

• Cuando s está el contexto de ejecución, es válido.
• Permanece válido hasta que sale de contexto de ejecución.

En este punto, la relación entre los contextos de ejecución y cuándo las variables son válidas es similar a la de otros lenguajes de programación. Ahora construiremos sobre este entendimiento al introducir el tipo String.

El Tipo String

Para ilustrar las reglas de ownership, necesitamos un tipo de datos más complejo que los que cubrimos en la sección “Tipos de Datos” del Capítulo 3. Los tipos cubiertos anteriormente son de un tamaño conocido, pueden almacenarse en el stack y se pueden sacar del stack cuando su contexto de ejecución termina, y se pueden copiar rápidamente y trivialmente para crear una nueva instancia independiente si otra parte del código necesita usar el mismo valor en un contexto de ejecución diferente. Pero queremos ver los datos que se almacenan en el heap y explorar cómo Rust sabe cuándo limpiar esos datos, y el tipo String es un gran ejemplo.

Nos centraremos en las partes de String que se relacionan con el ownership. Estos aspectos también se aplican a otros tipos de datos complejos, ya sean suministrados por la biblioteca estándar o creados por usted. Discutiremos String con más profundidad en el Capítulo 8.

Ya hemos visto literales de cadena, donde un valor de cadena está codificado en nuestro programa. Los literales de cadena son convenientes, pero no son adecuados para todas las situaciones en las que podríamos querer usar texto. Una razón es que son inmutables. Otra es que no todos los valores de cadena se pueden conocer cuando escribimos nuestro código: ¿y si queremos tomar la entrada del usuario y almacenarla? Para estas situaciones, Rust tiene un segundo tipo de cadena, String. Este tipo administra datos asignados en el heap y, como tal, es capaz de almacenar una cantidad de texto que no conocemos en el tiempo de compilación. Puede crear un String a partir de un literal de cadena usando la función from, así:

#![allow(unused)]
fn main() {
let s = String::from("hola");
}

El operador doble dos puntos :: nos permite usar el namespace (nombre de espacio) de esta función from particular bajo el tipo String en lugar de usar algún tipo de nombre como string_from. Discutiremos esta sintaxis más en la sección “Sintaxis de Método” del Capítulo 5, y cuando hablamos sobre el uso de namespaces con módulos en “Rutas para Referir a un Elemento en el Árbol de Módulos”

Este tipo de cadena puede ser mutable:

fn main() {
    let mut s = String::from("hola");

    s.push_str(", mundo!"); // push_str() agrega un literal a un String

    println!("{s}"); // Esto imprime "hola, mundo!"
}

Entonces, ¿cuál es la diferencia aquí? ¿Por qué String puede ser mutable pero los literales no pueden? La diferencia está en cómo estos dos tipos manejan la memoria.

Memoria y Asignación

En el caso de un literal de cadena, conocemos los contenidos en tiempo de compilación, por lo que el texto está codificado directamente en el ejecutable final. Es por eso que los literales de cadena son rápidos y eficientes. Pero estas propiedades solo vienen de la inmutabilidad del literal de cadena. Desafortunadamente, no podemos poner un blob de memoria en el binario para cada pieza de texto cuyo tamaño es desconocido en tiempo de compilación y cuyo tamaño puede cambiar mientras se ejecuta el programa.

Con el tipo String, para poder soportar una pieza mutable y extensible de texto, necesitamos asignar una cantidad de memoria en el heap, desconocida en tiempo de compilación, para contener el contenido. Esto significa:

• La memoria debe solicitarse al administrador de memoria en tiempo de ejecución.
• Necesitamos una forma de devolver esta memoria al administrador cuando terminemos con nuestro String.

Esa primera parte la hacemos nosotros: cuando llamamos a String::from, su implementación solicita la memoria que necesita. Esto es prácticamente universal en los lenguajes de programación.

Sin embargo, la segunda parte es diferente. En los lenguajes con un recolector de basura (Garbage Collector), el recolector de basura rastrea y limpia la memoria que ya no se está usando y no necesitamos pensar en ello. En la mayoría de los lenguajes sin un recolector de basura, es nuestra responsabilidad identificar cuándo la memoria ya no se está usando y llamar al código para liberarla explícitamente, tal como lo hicimos para solicitarla. Hacer esto correctamente ha sido históricamente un problema difícil de programación. Si lo olvidamos, desperdiciaremos memoria. Si lo hacemos demasiado pronto, tendremos una variable inválida. Si lo hacemos dos veces, eso también es un error. Necesitamos emparejar exactamente una asignación con exactamente una liberación.

Rust toma un camino diferente: la memoria se devuelve automáticamente una vez que la variable que la posee sale del contexto de ejecución. Aquí hay una versión de nuestro ejemplo de alcance de la Lista 4-1 usando un String en lugar de un literal de cadena:

fn main() {
    {
        let s = String::from("hola"); // s es valido desde aquí

        // Hacer algo con s
    }                                  // este ámbito termina aquí, 
                                       // s ya no es valido
}

Hay un punto natural en el que podemos devolver la memoria que necesita nuestro String al administrador: cuando s sale del alcance. Cuando una variable sale del contexto de ejecución, Rust llama a una función especial para nosotros. Esta función se llama drop, y es donde el autor de String puede poner el código para devolver la memoria. Rust llama a drop automáticamente en la llave de cierre.

Nota: En C++, este patrón de desasignación de recursos al final de la vida útil de un elemento a veces se denomina Resource Acquisition Is Initialization (RAII). La función drop en Rust será familiar para usted si ha utilizado patrones RAII.

Este patrón tiene un profundo impacto en la forma en que se escribe el código Rust. Puede parecer simple ahora, pero el comportamiento del código puede ser inesperado en situaciones más complejas cuando queremos que varias variables usen los datos que hemos asignado en el heap. Exploremos algunas de esas situaciones ahora.

Variables y datos interactuando con Move

Varias variables pueden interactuar con los mismos datos de diferentes formas en Rust. Veamos un ejemplo usando un entero en la Lista 4-2.

fn main() {
    let x = 5;
    let y = x;
}

Podemos adivinar lo que está haciendo: "vincular el valor 5 a x; luego hacer una copia del valor en x y vincularlo a y". Ahora tenemos dos variables, x y y, y ambos son 5. Esto es lo que está sucediendo, porque los enteros son valores simples con un tamaño conocido y fijo, y estos dos valores 5 se empujan en la pila.

Ahora veamos la versión String:

fn main() {
    let s1 = String::from("hola");
    let s2 = s1;
}

Esto se ve muy similar, por lo que podríamos suponer que la forma en que funciona sería la misma: es decir, la segunda línea haría una copia del valor en s1 y lo vincularía a s2. Pero esto no es exactamente lo que sucede.

Mire la Figura 4-1 para ver lo que está sucediendo en realidad con el String. Un String está compuesto por tres partes, mostradas a la izquierda: un puntero a la memoria que contiene el contenido de la cadena, una longitud y una capacidad. Este grupo de datos se almacena en la pila. A la derecha está la memoria en el heap que contiene el contenido.

Figura 4-1: Representación en memoria de un String que contiene el valor "hola" vinculado a s1

La longitud es cuánta memoria, en bytes, los contenidos del String están utilizando actualmente. La capacidad es la cantidad total de memoria, en bytes, que el String ha recibido del administrador. La diferencia entre longitud y capacidad importa, pero no en este contexto, por lo que por ahora está bien ignorar la capacidad.

Cuando asignamos s1 a s2, los datos de String se copian, lo que significa que copiamos el puntero, la longitud y la capacidad que están en la pila. No copiamos los datos en el heap al que hace referencia el puntero. En otras palabras, la representación de datos en memoria se ve como la Figura 4-2.

Figura 4-2: Representación en memoria de la variable s2 que tiene una copia del puntero, la longitud y la capacidad de s1.

La representación no se ve como la Figura 4-3, que es lo que la memoria parecería si Rust copiara además los datos del heap. Si Rust hiciera esto, la operación s2 = s1 podría ser muy costosa en términos de rendimiento de tiempo de ejecución si los datos en el heap fueran grandes.

Figura 4-3: Otra posibilidad de lo que s2 = s1 podría hacer si Rust copiara también los datos del heap

Anteriormente, dijimos que cuando una variable sale de contexto de ejecución, Rust llama automáticamente a la función drop y limpia la memoria del heap para esa variable. Pero la Figura 4-2 muestra que ambos punteros de datos apuntan al mismo lugar. Esto es un problema: cuando s2 y s1 salen de contexto de ejecución, ambos intentarán liberar la misma memoria. Esto se conoce como un error de doble liberación y es uno de los errores de seguridad de la memoria que mencionamos anteriormente. Liberar la memoria dos veces puede conducir a la corrupción de memoria, lo que puede conducir a vulnerabilidades de seguridad.

Para garantizar la seguridad de la memoria, después de la línea let s2 = s1;, Rust considera a s1 como no válida. Por lo tanto, Rust no necesita liberar nada cuando s1 sale de ámbito. Echa un vistazo a lo que sucede cuando intentas usar s1 después de que se crea s2; no funcionará:

fn main() {
    let s1 = String::from("hola");
    let s2 = s1;

    println!("{s1}, mundo!");
}

Obtendrás un error como este porque Rust te impide usar la referencia invalidada:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:15
  |
2 |     let s1 = String::from("hola");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, mundo!");
  |               ^^^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

For more information about this error, try `rustc --explain E0382`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Si has escuchado los términos copia superficial y copia profunda mientras trabajabas con otros lenguajes, el concepto de copiar el puntero, la longitud y la capacidad sin copiar los datos probablemente suene a hacer una copia superficial. Pero debido a que Rust también invalida la primera variable, en vez de llamarse una copia superficial, se conoce como un movimiento. En este ejemplo, diríamos que s1 fue movido a s2. Entonces, lo que realmente sucede se muestra en la Figura 4-4.

Figura 4-4: Representación en memoria después de que s1 se haya invalidado

¡Eso resuelve nuestro problema! Con solo s2 válido, cuando sale de ámbito solo él liberará la memoria, y ya está.

Además, hay una elección de diseño que se infiere de esto: Rust nunca creará automáticamente "copias profundas" de tus datos. Por lo tanto, cualquier copia automática se puede asumir que es económica en términos de rendimiento en tiempo de ejecución.

Alcance y Asignación

Lo inverso también es cierto para la relación entre el alcance, la propiedad y la liberación de memoria mediante la función drop. Cuando asignas un valor completamente nuevo a una variable existente, Rust llamará a drop y liberará inmediatamente la memoria del valor original. Considera este código, por ejemplo:

fn main() {
    let mut s = String::from("hola");
    s = String::from("ahoy");

    println!("{s}, mundo!");
}

Inicialmente, declaramos una variable s y la vinculamos a un String con el valor "hola". Luego, inmediatamente creamos un nuevo String con el valor "ahoy" y lo asignamos a s. En este punto, nada hace referencia al valor original en el heap.

Figura 4-5: Representación en memoria después de que el valor inicial ha sido completamente reemplazado.

El string original, por lo tanto, sale inmediatamente de su alcance. Rust ejecutará la función drop sobre él y su memoria será liberada de inmediato. Cuando imprimimos el valor al final, será "ahoy, mundo!".

Variables y datos interactuando con Clone

Si queremos copiar profundamente los datos del heap de la String, no solo los datos de la pila, podemos usar un método común llamado clone. Discutiremos la sintaxis del método en el Capítulo 5, pero debido a que los métodos son una característica común en muchos lenguajes de programación, probablemente los hayas visto antes.

Aquí hay un ejemplo del método clone en acción:

fn main() {
    let s1 = String::from("hola");
    let s2 = s1.clone();

    println!("s1 = {s1}, s2 = {s2}");
}

Esto funciona bien y produce explícitamente el comportamiento mostrado en la Figura 4-3, donde los datos del heap se copian.

Cuando veas una llamada a clone, sabrás que se está ejecutando algún código arbitrario y que ese código puede ser costoso. Es un indicador visual de que algo diferente está sucediendo.

Solo datos del stack: Copiar

Hay otro problema que aún no hemos hablado. Este código usando enteros - parte de lo que se mostró en el Listado 4-2 - funciona y es válido:

fn main() {
    let x = 5;
    let y = x;

    println!("x = {x}, y = {y}");
}

Pero este código parece contradecir lo que acabamos de aprender: no tenemos una llamada a clone, pero x sigue siendo válido y no se movió a y.

La razón es que los tipos como los enteros que tienen un tamaño conocido en el momento de la compilación se almacenan completamente en la pila, por lo que copiar los valores reales es rápido. Eso significa que no hay razón para que queramos evitar que x sea válido después de crear la variable y. En otras palabras, no hay diferencia entre copiar superficial y profunda aquí, por lo que llamar a clone no haría nada diferente de la copia superficial habitual, y podemos dejarlo fuera.

Rust tiene una anotación especial llamada Copy que podemos colocar en tipos que se almacenan en la pila, como los enteros (hablaremos más sobre los traits en el Capítulo 10). Si un tipo implementa el Copy trait, las variables que lo usan no se mueven, sino que se copian trivialmente, haciendo que sigan siendo válidas después de asignarlas a otra variable.

Rust no nos permitirá anotar un tipo con Copy si el tipo, o cualquiera de sus partes, ha implementado el trait Drop. Si el tipo necesita que algo especial suceda cuando el valor sale del alcance y agregamos la anotación Copy a ese tipo, obtendremos un error de tiempo de compilación. Para aprender cómo agregar la anotación Copy a tu tipo para implementar el trait, consulta “Traits derivables” en el Apéndice C.

Entonces, ¿qué tipos implementan el trait Copy? Puedes consultar la documentación del tipo dado para asegurarte, pero como regla general, cualquier grupo de valores escalares simples puede implementar Copy, y nada que requiera asignación o sea alguna forma de recurso puede implementar Copy. Aquí hay algunos de los tipos que implementan Copy:

• Todos los tipos enteros, como u32.
• El tipo booleano, bool, con valores true y false.
• Todos los tipos de punto flotante, como f64.
• El tipo de carácter, char.
• Tuplas, si solo contienen tipos que también implementan Copy. Por ejemplo, (i32, i32) implementa Copy, pero (i32, String) no lo hace.

Propiedad y funciones

Las mecánicas de pasar un valor a una función son similares a las de asignar un valor a una variable. Pasar una variable a una función moverá o copiará, como hace la asignación. La Lista 4-3 tiene un ejemplo con algunas anotaciones que muestran dónde entran y salen las variables del alcance.

fn main() {
    let s = String::from("hola");  // s aparece en el ámbito

    tomar_ownership(s);             // El valor de s se mueve a la función...
                                    // ... y ya no es valido aquí

    let x = 5;                      // x aparece en el ámbito

    hacer_una_copia(x);             // x deberia moverse a la función,
                                    // pero i32 implementa Copy, entonces es
    println!("{}", x);              // valido aún despues de llamar a la función

} // Aquí termina el ámbito, x es destruido con drop. La memoria es liberada.
  // s ya no existia porque habia sido movido a la función.
  // Nada especial ocurre.

fn tomar_ownership(un_string: String) { // un_string aparece en el ámbito
    println!("{un_string}");
} // Aquí termina el ámbito, un_string es destruido con drop. 
  // La memoria es liberada.

fn hacer_una_copia(un_entero: i32) { // un_entero aparece en el ámbito
    println!("{un_entero}");
} // Aquí termina el ámbito, un_entero es destruido. Nada especial ocurre.

Si intentamos usar s después de llamar a tomar_ownership, Rust lanzaría un error de tiempo de compilación. Estas comprobaciones estáticas nos protegen de errores. Intenta agregar código a main que use s y x para ver dónde puedes usarlos y dónde las reglas de propiedad te impiden hacerlo.

Valores de retorno y alcance

Los valores de retorno también pueden transferir la propiedad. La Lista 4-4 muestra un ejemplo de una función que devuelve algún valor, con anotaciones similares a las de la Lista 4-3.

fn main() {
    let s1 = da_un_ownership();         // da_un_ownership es llamado y
                                        // devuelve el valor de retorno
                                        // a s1

    let s2 = String::from("hola");     // s2 aparece en el ámbito

    let s3 = toma_y_devuelve(s2);  // s2 es movido a la función
                                        // toma_y_devuelve, que también
                                        // retorna el valor de s2 a s3
} // Fin el ámbito, s3 es destruido con drop y se libera la memoria. 
  // s2 fue movido previamente, entonces no pasa nada. 
  // s1 es destruido con drop y se libera la memoria.

fn da_un_ownership() -> String {             // da_un_ownership mueve su
                                             // retorno a la función que la
                                             // llama

    let un_string = String::from("tuyo");    // un_string aparece en el ámbito

    un_string                                // un_string es retornado y
                                             // mueve su valor
}

// Esta función toma un String y devuelve uno
fn toma_y_devuelve(un_string: String) -> String { // un_string aparece 
                                                  // en el ámbito

    un_string  // un_string es retornado y mueve su valor
}

La propiedad (ownership) de una variable sigue el mismo patrón cada vez: asignar un valor a otra variable lo mueve. Cuando una variable que incluye datos en el heap sale del contexto de ejecución, el valor se limpiará por drop a menos que la propiedad de los datos se haya movido a otra variable.

Aunque esto funciona, tomar la propiedad y luego devolver la propiedad con cada función es un poco tedioso. ¿Qué pasa si queremos que una función use un valor pero no tome la propiedad? Es bastante molesto que todo lo que pasamos también necesite volver a pasar si queremos usarlo de nuevo, además de cualquier dato que resulte del cuerpo de la función que también podríamos querer devolver.

Rust nos permite devolver múltiples valores usando una tupla, como se muestra en la Lista 4-5.

fn main() {
    let s1 = String::from("hola");

    let (s2, len) = calcular_longitud(s1);

    println!("La longitud de '{s2}' es {len}.");
}

fn calcular_longitud(s: String) -> (String, usize) {
    let length = s.len(); // len() retorna la longitud de un String

    (s, length)
}

Pero esto es demasiado ceremonioso y mucho trabajo para un concepto que debería ser común. Afortunadamente para nosotros, Rust tiene una característica para usar un valor sin transferir la propiedad, llamada referencias.

Referencias y Prestamos

El problema con la tupla de código en el Listado 4-5 es que tenemos que devolver el String a la función que lo llama para que podamos seguir usando el String después de la llamada a calcular_longitud, porque el String se movió a calcular_longitud. En lugar de eso, podemos proporcionar una referencia al valor String. Una referencia es como un puntero en que es una dirección que podemos seguir para acceder a los datos almacenados en esa dirección; esos datos son propiedad de otra variable. A diferencia de un puntero, una referencia garantiza que apunte a un valor válido de un tipo particular para la vida de esa referencia.

Aquí está cómo definirías y usarías una función calcular_longitud que tiene una referencia a un objeto como parámetro en lugar de tomar la propiedad del valor.

fn main() {
    let s1 = String::from("hola");

    let len = calcular_longitud(&s1);

    println!("La longitud de '{s1}' es {len}.");
}

fn calcular_longitud(s: &String) -> usize {
    s.len()
}

Primero, ten en cuenta que todo el código de la tupla en la declaración de la variable y el valor de retorno de la función ha desaparecido. En segundo lugar, observe que pasamos &s1 a calcular_longitud y, en su definición, tomamos &String en lugar de String. Este signo ampersands (&) representa referencia, y te permiten referirte a algún valor sin tomar la propiedad de él. La Figura 4-6 representa este concepto.

Figura 4-6: Un diagrama de &String s apuntando a String s1

Nota: Lo opuesto a la referencia usando & es desreferenciar, que se logra con el operador de desreferencia, *. Veremos algunos usos del operador de desreferencia en el Capítulo 8 y discutiremos detalles de la desreferenciación en el Capítulo 15.

Vamos a echar un vistazo más de cerca a la llamada de función aquí:

fn main() {
    let s1 = String::from("hola");

    let len = calcular_longitud(&s1);

    println!("La longitud de '{s1}' es {len}.");
}

fn calcular_longitud(s: &String) -> usize {
    s.len()
}

La sintaxis &s1 nos permite crear una referencia que se refiere al valor de s1 pero sin ser el propietario. Por este motivo, el valor al que apunta no se descartará cuando la referencia deje de usarse.

Del mismo modo, la firma de la función usa & para indicar que el tipo del parámetro s es una referencia. Vamos a agregar algunas anotaciones:

fn main() {
    let s1 = String::from("hola");

    let len = calcular_longitud(&s1);

    println!("La longitud de '{s1}' es {len}.");
}

fn calcular_longitud(s: &String) -> usize { // es una referencia a un String
    s.len()
} // Aquí, s sale de ámbito. Pero como no tiene el ownership/la propiedad sino 
  // que s es solo un prestamo, no se destruye, se regresa al propietario, s1.

El contexto de ejecución en el que la variable s es válida es el mismo que el contexto de ejecución de cualquier parámetro de función, pero el valor al que apunta la referencia no se descarta cuando s deja de usarse, porque s no tiene la propiedad. Cuando las funciones tienen referencias como parámetros en lugar de los valores reales, no necesitaremos devolver los valores para devolver la propiedad, porque nunca tuvimos la propiedad.

Llamamos a la acción de crear una referencia prestar (borrowing en ingles). Como en la vida real, si una persona posee algo, puedes pedir prestado. Cuando termines, tienes que devolverlo. No lo posees.

Entonces, ¿qué pasa si intentamos modificar algo que estamos prestando? Prueba el código en el Listado 4-6. Spoiler alert: ¡no funciona!

fn main() {
    let s = String::from("hola");

    modificar(&s);
}

fn modificar(un_string: &String) {
    un_string.push_str(", mundo");
}

Aquí está el error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*un_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
8 |     un_string.push_str(", world");
  |     ^^^^^^^^^^^ `un_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn modificar(un_string: &mut String) {
  |                         +++

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Al igual que las variables son inmutables por defecto, también lo son las referencias. No se nos permite modificar algo al que tenemos una referencia.

Referencias Mutables

Podemos arreglar el código del Listado 4-6 para permitirnos modificar un valor prestado con solo unos pequeños cambios que usen, en su lugar, una referencia mutable:

fn main() {
    let mut s = String::from("hola");

    modificar(&mut s);
}

fn modificar(un_string: &mut String) {
    un_string.push_str(", mundo");
}

Primero cambiamos s a mut. Luego creamos una referencia mutable con &mut s donde llamamos a la función modificar, y actualizamos la firma de la función para aceptar una referencia mutable con un_string: &mut String. Esto hace muy claro que la función modificar mutará el valor que presta.

Las referencias mutables tienen una gran restricción: si tienes una referencia mutable a un valor, no puedes tener otras referencias a ese valor. Este código que intenta crear dos referencias mutables a s fallará:

fn main() {
    let mut s = String::from("hola");

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{}, {}", r1, r2);
}

Aquí está el error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{}, {}", r1, r2);
  |                        -- first borrow later used here

For more information about this error, try `rustc --explain E0499`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Este error dice que este código es inválido porque no podemos prestar s como mutable más de una vez. El primer préstamo mutable está en r1 y debe durar hasta que se use en el println!, pero entre la creación de esa referencia mutable y su uso, intentamos crear otra referencia mutable en r2 que presta los mismos datos que r1.

La restricción que impide múltiples referencias mutables a los mismos datos al mismo tiempo permite la mutación pero de una manera muy controlada. Es algo con lo que los nuevos Rustaceans luchan porque la mayoría de los lenguajes te permiten mutar cuando quieras. El beneficio de tener esta restricción es que Rust puede prevenir las carreras de datos en tiempo de compilación. Una carrera de datos es similar a una condición de carrera y ocurre cuando ocurren estos tres comportamientos:

• Dos o más punteros acceden a los mismos datos al mismo tiempo.
• Al menos uno de los punteros se está utilizando para escribir en los datos.
• No hay ningún mecanismo que se esté utilizando para sincronizar el acceso a los datos.

Las carreras de datos causan un comportamiento indefinido y pueden ser difíciles de diagnosticar y corregir cuando intentas rastrearlas en tiempo de ejecución; ¡Rust evita este problema al negarse a compilar código con carreras de datos!

Como siempre, podemos usar llaves para crear un nuevo contexto de ejecución, permitiendo múltiples referencias mutables, solo no simultáneas:

fn main() {
    let mut s = String::from("hola");

    {
        let r1 = &mut s;
    } // r1 se sale de su ámbito aquí, por lo que no hay problema 
      // si creamos otra referencia mutable

    let r2 = &mut s;
}

Rust impone una regla similar para combinar referencias mutables e inmutables. Este código da como resultado un error:

fn main() {
    let mut s = String::from("hola");

    let r1 = &s; // no hay problema
    let r2 = &s; // no hay problema
    let r3 = &mut s; // ¡ UN GRAN PROBLEMA !

    println!("{}, {}, y {}", r1, r2, r3);
}

Aquí está el error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no hay problema
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no hay problema
6 |     let r3 = &mut s; // ¡ UN GRAN PROBLEMA !
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{}, {}, y {}", r1, r2, r3);
  |                                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

¡Uf! También no podemos tener una referencia mutable mientras tenemos una inmutable al mismo valor.

¡Los usuarios de una referencia inmutable no esperan que el valor cambie repentinamente debajo de ellos! Sin embargo, se permiten múltiples referencias inmutables porque nadie que solo está leyendo los datos tiene la capacidad de afectar la lectura de los datos de nadie más.

Tenga en cuenta que el contexto de ejecución de una referencia comienza desde donde se introduce y continúa hasta la última vez que se usa la referencia. Por ejemplo, este código se compilará porque el último uso de las referencias inmutables, el println!, ocurre antes de que se introduzca la referencia mutable:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no hay problema
    let r2 = &s; // no hay problema
    println!("{r1} y {r2}");
    // variables r1 y r2 no se usaran más a partir de aquí

    let r3 = &mut s; // no hay problema
    println!("{r3}");
}

Los contextos de ejecución de las referencias inmutables r1 y r2 terminan después del println! donde se usan por última vez, que es antes de que se cree la referencia mutable r3. Estos contextos de ejecución no se superponen, por lo que este código está permitido: ¡el compilador puede decir que la referencia ya no se está utilizando en un punto antes del final del ámbito!

Aunque los errores de préstamo a veces pueden ser frustrantes, recuerda que es el compilador de Rust que señala un error potencial temprano (en tiempo de compilación en lugar de en tiempo de ejecución) y te muestra exactamente dónde está el problema. Entonces no tienes que rastrear por qué tus datos no son lo que pensabas que eran.

Referencias colgantes

En lenguajes con punteros, es fácil crear accidentalmente un puntero colgante: un puntero que hace referencia a una ubicación en la memoria que puede haber sido otorgada a otra persona, al liberar algo de memoria mientras se preserva un puntero a esa memoria. En Rust, por el contrario, el compilador garantiza que las referencias nunca serán referencias colgantes: si tiene una referencia a algún dato, el compilador asegurará que los datos no salgan de contexto de ejecución antes de que la referencia a los datos lo haga.

Intentemos crear una referencia colgante para ver cómo Rust los previene con un error de tiempo de compilación:

fn main() {
    let referencia_a_la_nada = colgar();
}

fn colgar() -> &String {
    let s = String::from("hola");

    &s
}

Aquí está el error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn colgar() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn colgar() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

error[E0515]: cannot return reference to local variable `s`
 --> src/main.rs:8:5
  |
8 |     &s
  |     ^^ returns a reference to data owned by the current function

Some errors have detailed explanations: E0106, E0515.
For more information about an error, try `rustc --explain E0106`.
error: could not compile `ownership` (bin "ownership") due to 2 previous errors

Este mensaje de error se refiere a una característica que aún no hemos cubierto: los tiempos de vida. Discutiremos los tiempos de vida en detalle en el Capítulo 10. Pero, si ignora las partes sobre los tiempos de vida, el mensaje contiene la clave para saber por qué este código es un problema:

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

Se traduciría algo así como:

el tipo de retorno de la función contiene un valor prestado, pero no hay ningún 
valor que pueda ser prestado
```

<Listing file-name="src/main.rs">

```rust,ignore,does_not_compile
# fn main() {
#     let referencia_a_la_nada = colgar();
# }
# 
fn colgar() -> &String { // colgar retorna una referencia a un String

    let s = String::from("hola"); // s es un nuevo String

    &s // retornamos una referencia a la String, s
} // Aquí, s sale de ámbito y se libera su memoria. 
  // ¡Pero retornamos una referencia a ella!
  // ¡Peligro! ¡Esta referencia apunta a memoria que ya no existe!
```

</Listing>

Porque `s` se crea dentro de `colgar`, cuando el código de `colgar` finaliza,
`s` se desalocará. Pero intentamos devolver una referencia a él. Eso significa
que esta referencia estaría apuntando a una `String` inválida. ¡Eso no está
bien! Rust no nos dejará hacer esto.

La solución aquí es devolver la `String` directamente:

```rust
# fn main() {
#     let string = no_colgante();
# }
# 
fn no_colgante() -> String {
    let s = String::from("hola");

    s
}
```

Esto funciona sin problemas. La propiedad se mueve fuera y nada se desaloca.

### Las reglas de las referencias

Repasemos lo que hemos discutido sobre las referencias:

- En cualquier momento dado, puedes tener *o bien* una referencia mutable *o*
  cualquier número de referencias inmutables.
- Las referencias deben ser siempre válidas.

A continuación, veremos un tipo diferente de referencia: los slices.

El Tipo Slice

Los Slices te permiten referenciar a una secuencia contigua de elementos en una colección en lugar de la colección completa. Un slice es una especie de referencia, por lo que no tiene ownership.

Aquí hay un pequeño problema de programación: escribe una función que tome un string de palabras separadas por espacios y retorne la primera palabra que encuentre en ese string. Si la función no encuentra ningún espacio en el string, todo el string debe ser una sola palabra, por lo que se debe retornar todo el string.

Trabajemos en cómo escribiríamos la firma de esta función sin usar slices, para entender el problema que los slices resolverán:

fn first_word(s: &String) -> ?

La función first_word tiene un &String como parámetro. No queremos el ownership, así que esto está bien. Pero ¿Que deberíamos retornar? Realmente no tenemos una forma de hablar sobre "una porción de un string". Sin embargo, podríamos retornar el índice del final de la palabra, indicado por un espacio. Probemos eso, como se muestra en Listing 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Dado que necesitamos recorrer el String elemento por elemento y comprobar si un valor es un espacio, convertiremos nuestro String a un array de bytes usando el método as_bytes.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

A continuación, creamos un iterator sobre el array de bytes utilizando el método iter:

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Hablaremos más detalladamente sobre los iterators en Procesando una serie de elementos con Iteradores. Por ahora, sabemos que iter es un método que retorna cada elemento en una colección y que enumerate envuelve el resultado de iter y retorna cada elemento como parte de una tupla. El primer elemento de la tupla que retorna enumerate es el índice, y el segundo elemento es una referencia al elemento. Esto es un poco más conveniente que calcular el índice nosotros mismos.

Debido a que el método enumerate retorna una tupla, podemos usar patrones para desestructurar esa tupla. Hablaremos más sobre los patrones en Patrones que vinculan valores. En el ciclo for, especificamos un patrón que tiene i para el índice de la tupla e &item para el byte único en la tupla. Debido a que tomamos una referencia al elemento de .iter().enumerate(), podemos usar& en el patrón.

Dentro del ciclo for, buscamos el byte que representa el espacio usando la sintaxis literal del byte. Si encontramos un espacio, retornamos su posición. De lo contrario, retornamos la longitud del string usando s.len().

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

Ahora tenemos una forma de averiguar el índice del final de la primera palabra en el string, pero tenemos un problema. Estamos retornando un usize por si solo, pero es solo un número significativo en el contexto de él &String. En otras palabras, debido a que es un valor separado del String, no hay garantía de que siga siendo válido en el futuro. Considera el programa en Listing 4-8 que usa la función first_word del Listing 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s); // word obtendrá el valor 5

    s.clear(); // esto "vacía" el String, dejando s igual a ""

    // word aún tiene el valor 5 aquí, pero ya no hay un string para que
    // usar el valor 5 tenga sentido, ¡word es totalmente invalida!
}

Este programa compila sin errores y también lo hará si usáramos word después de llamar a s.clear(). Debido a que word no está conectado al estado de s en absoluto, word aún contiene el valor 5. Podríamos usar el valor 5 con la variable s para intentar extraer la primera palabra, pero esto sería un error porque el contenido de s ha cambiado desde que guardamos 5 en word.

¡Tener que preocuparse de que el índice de word no esté sincronizado con los datos en s es tedioso y propenso a errores! El manejo de estos índices es aún más frágil si escribimos una segunda función llamada second_word. Su firma debería ser algo como esto:

fn second_word(s: &String) -> (usize, usize) {

Ahora que estamos rastreando tanto el índice de inicio como el de fin, y tenemos aún más que se calcularon a partir de los datos en un estado particular, pero que no están vinculados a ese estado en absoluto. Tenemos tres variables no relacionados flotando por ahi que necesitan mantenerse sincronizadas.

Afortunadamente, Rust tiene una solución a este problema: los string slices.

String Slices

Un string slice es una referencia de parte de un String, y se ve algo como esto:

fn main() {
    let s = String::from("hello world");

    let hello = &s[0..5];
    let world = &s[6..11];
}

En lugar de referenciar todo el String, hello es una referencia a una porción del String, especificada en el segmento adicional [0..5]. Creamos slices usando un rango dentro de corchetes, especificando [starting_index..ending_index], donde starting_index es la primera posición en el slice y ending_index es una posición más que la última posición en el slice. Internamente, la estructura de datos del slice almacena la posición inicial y la longitud del slice, lo que corresponde a ending_index menos starting_index. Por lo tanto, en el caso de let world = &s[6..11];, world sería un slice que contiene un puntero al byte en el índice 6 de s con un valor de longitud de 5.

Figure 4-7 muestra esto en el diagrama.

Figure 4-7: String slice referencia una parte de un String

Con la sintaxis de rango .. de Rust, si queremos comenzar en el índice 0, podemos dejar el valor antes de los dos puntos. En otras palabras, estos son iguales:

let s = String::from("hello");

let slice = &s[0..2];
let slice = &s[..2];

Del mismo modo, si el slice incluye el último byte del String, podemos eliminar el número final. Esto significa que son iguales:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

También podemos omitir ambos valores para tomar un slice de todo el string. Entonces estos son iguales:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

Nota: Los índices del rango del string slice deben ocurrir en límites válidos de caracteres UTF-8. Si intentamos crear un string slice en medio de un caracter multibyte, tu programa saldrá con un error. Para fines de introducción a los string slices, estamos asumiendo solo ASCII en esta sección; una discusión más completa sobre el manejo de UTF-8 se encuentra en la sección Almacenando texto codificado en UTF-8 con Strings del Capítulo 8.

Con toda esta información en mente, reescribamos first_word para retornar un slice. El tipo que significa “string slice” se escribe como &str:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

Obtenemos el índice para el final de la palabra de la misma manera que lo hicimos en el Listing 4-7, buscando la primera aparición de un espacio. Cuando encontramos un espacio, retornamos un string slice usando el inicio del string y el índice del espacio como índices de inicio y final.

Ahora cuando llamamos a first_word, obtenemos un único valor que está vinculado a los datos subyacentes. El valor se compone de una referencia al punto de inicio del slice y el número de elementos en el slice.

Retornando el slice también funcionaría para la función second_word:

fn second_word(s: &String) -> &str {

Ahora tenemos una API sencilla que es mucho más difícil de estropear porque el compilador se asegurará de que las referencias dentro del String sigan siendo válidas. ¿Recuerdas el error en el programa en Listing 4-8, cuando obtuvimos el índice para el final de la primera palabra, pero luego limpiamos el string de modo que nuestro índice era inválido? Ese código era lógicamente incorrecto, pero no mostraba errores inmediatos. Los problemas aparecerían más tarde si seguimos intentando usar el índice de la primera palabra con un string vacío. Los Slices hacen que este error sea imposible y nos permiten saber que tenemos un problema en nuestro código mucho antes. El uso de la versión slice de first_word arrojará un error en tiempo de compilación:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

Aquí está el error del compilador:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                  ------ immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

Recordemos que las reglas del borrowing si tenemos una referencia immutable a algo, no podemos tomar también una referencia mutable. Debido a que clear necesita truncar el String, necesita obtener una referencia mutable. El println! después de la llamada a clear usa la referencia en word, por lo que la referencia inmutable debe seguir activa en ese punto. Rust impide que la referencia mutable en clear y la referencia inmutable en word existan al mismo tiempo, y la compilación falla. No solo Rust ha hecho más fácil nuestra API, sino que también ha eliminado una clase entera de errores en tiempo de compilación.

String Literales como Slices

Recordemos que hablamos sobre que los string literales se almacenan dentro del binario. Ahora que sabemos sobre los slices, podemos entender correctamente los string literales:

#![allow(unused)]
fn main() {
let s = "Hello, world!";
}

El tipo de s aquí es &str: es un slice apuntando a ese punto específico del binario. Esto también es por qué los literales de string son inmutables; &str es una referencia inmutable.

String Slices as Parameters

Conociendo que puedes tomar slices de literales y valores String nos lleva a una mejora más en first_word, y es su firma:

fn first_word(s: &String) -> &str {

Un Rustacean más experimentado escribiría la firma mostrada en el Listing 4-9 en su lugar porque nos permite usar la misma función en ambos valores &String y &str.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` funciona con slices de un string, sean parciales o completos.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` también funciona con referencias de un string, que son equivalentes
    // a un slice completo de un String
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` funciona con slices de string literales, sean parciales o completos
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Por que los strings literales son slices de strings,esto también funciona,
    // sin necesidad de usar la sintaxis de slices.
    let word = first_word(my_string_literal);
}

Si tenemos un string slice, podemos pasar directamente ese valor. Si tenemos un String, podemos pasar un slice del String o una referencia al String. Esta flexibilidad aprovecha las deref coercions, una característica que veremos en la sección "Tratando los Smart Pointers como Referencias Regulares con el Trait Deref" del Capítulo 15.

Definir una función para tomar un string slice en lugar de una referencia a un String hace que nuestra API sea más general y útil sin perder ninguna funcionalidad:

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` funciona con slices de un string, sean parciales o completos.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` también funciona con referencias de un string, que son equivalentes
    // a un slice completo de un String
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` funciona con slices de string literales, sean parciales o completos
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Por que los strings literales son slices de strings,esto también funciona,
    // sin necesidad de usar la sintaxis de slices.
    let word = first_word(my_string_literal);
}

Otros Slices

Los string slices, como puedes imaginar, son específicos para strings. Pero hay un tipo de slice más general. Considera este array:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];
}

Así como podemos querer referirnos a parte de un string, también podemos querer referirnos a parte de un array. Lo haríamos de esta manera:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

Este slice tiene el tipo &[i32]. Funciona de la misma manera que los slices de string, almacenando una referencia al primer elemento y una longitud. Usarás este tipo de slice para todo tipo de colecciones. Hablaremos de estas colecciones en detalle cuando veamos vectores en el Capítulo 8.

Resumen

Los conceptos de ownership, borrowing, y slices aseguran la seguridad de la memoria en los programas Rust en tiempo de compilación. El lenguaje Rust te da control sobre el uso de la memoria de la misma manera que otros lenguajes de programación de sistemas, pero el hecho de que el propietario de los datos limpie automáticamente esos datos cuando salen del scope significa que no tienes que escribir y depurar código extra para obtener este control.

El ownership afecta a cómo funcionan otras partes de Rust, así que hablaremos de estos conceptos más adelante en el libro. Vamos a pasar al Capítulo 5 y ver cómo agrupar piezas de datos en un struct.

Usando Structs para Estructurar Datos Relacionados

Un struct, o estructura, es un tipo de dato personalizado que te permite empaquetar y nombrar múltiples valores relacionados que forman un grupo significativo. Si estás familiarizado con un lenguaje orientado a objetos, un struct es como los atributos de un objeto. En este capítulo, compararemos y contrastaremos tuplas con structs para desarrollar lo que ya sabes y demostrar cuando los structs son una mejor manera de agrupar datos.

Demostraremos cómo definir e instanciar structs. Discutiremos como definir funciones asociadas, especialmente, el tipo de funciones asociadas llamadas métodos, para especificar el comportamiento asociado con un tipo de struct. Los structs y enums (discutidos en el capítulo 6) son los bloques de construcción para crear nuevos tipos en el dominio de tu programa para aprovechar al máximo la comprobación de tipos en tiempo de compilación de Rust.

Definiendo e Instanciando Structs

Los Structs son similares a las tuplas, discutido en la sección “The Tuple Type” en ambos casos mantenemos múltiples valores relativos. Como en las tuplas, las partes de un struct pueden ser de diferentes tipos. A diferencia de las tuplas, en un struct tú nombras a cada pieza de datos para que quede claro, que significan estos valores. Agregando estos nombres significa que los structs son más flexibles que las tuplas: no tienes que confiar en el orden de los datos para especificar o acceder a los valores de una instancia.

Para definir un struct, debemos usar la palabra clave struct y el nombre del struct completo. El nombre del struct debe describir el significado de los datos que se agrupan. Entonces, entre llaves, definimos los nombres y tipos de datos, que llamaremos campos. Por ejemplo, en el Listing 5-1 mostramos una definición de un struct que almacena información sobre una cuenta de usuario.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

Para usar un struct después de haberlo definido, creamos una instancia de ese struct especificando valores concretos para cada uno de los campos. Creamos una instancia al declarar el nombre del struct y luego agregar llaves que contienen clave: valor pares, donde las claves son los nombres de los campos y los valores son los datos que queremos almacenar en esos campos. No tenemos que especificar los campos en el mismo orden en el que los declaramos en el struct. En otras palabras, la definición del struct es como una plantilla general para el tipo, y las instancias llenan esa plantilla con datos particulares para crear valores del tipo. Por ejemplo, podemos declarar un usuario en particular como se muestra en el Listing 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

Para acceder a un valor específico de un struct, usamos la notación de punto. Por ejemplo, para acceder a la dirección de correo electrónico de este usuario, usamos user1.email. Si la instancia es mutable, podemos cambiar un valor asignando en un campo particular. El Listing 5-3 muestra cómo cambiar el valor en el campo email de una instancia mutable de User.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

Nota que toda la instancia debe ser mutable; Rust no nos permite marcar solo ciertos campos como mutables. Como cualquier expresión, podemos construir una nueva instancia del struct como la última expresión en el cuerpo de la función para devolver implícitamente esa nueva instancia.

Listing 5-4 muestra una función build_user que devuelve una instancia de User con el correo electrónico y el nombre de usuario dados. El campo active obtiene el valor de true, y el campo sign_in_count obtiene el valor de 1.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Tiene sentido nombrar los parámetros de la función con el mismo nombre que los campos del struct, pero tener que repetir los nombres de los campos y variables email y username es un poco tedioso. Si el struct tuviera más campos, repetir cada nombre sería aún más molesto. Afortunadamente, hay una conveniente forma abreviada.

Usando la abreviatura Field Init

Debido a que los nombres de los parámetros y los nombres de los campos del struct son exactamente los mismos en el Listing 5-4, podemos usar la abreviatura Field Init para reescribir build_user para que se comporte exactamente igual pero no tenga la repetición de username y email, como se muestra en el Listing 5-5.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

Aquí, estamos creando una nueva instancia del struct User, que tiene un campo llamado email. Queremos establecer el valor del campo email en el valor del parámetro email de la función build_user. Debido a que el campo email y el parámetro email tienen el mismo nombre, solo necesitamos escribir email en lugar de email: email.

Creando Instancias de Otras Instancias con Sintaxis de Struct Update

Suele ser útil crear una nueva instancia de un struct que incluya la mayoría de los valores de otra instancia, pero cambie algunos. Puede hacer esto usando la sintaxis de struct update.

Primero, en el Listing 5-6 mostramos cómo crear una nueva instancia de User regularmente, sin la sintaxis de actualización. Establecemos un nuevo valor para email, pero de lo contrario usamos los mismos valores de user1 que creamos en el Listing 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

Usando la sintaxis de struct update, podemos lograr el mismo efecto con menos código, como se muestra en el Listing 5-7. La sintaxis .. especifica que los campos restantes que no se establecen explícitamente deben tener el mismo valor que los campos en la instancia dada.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

El código en el Listing 5-7 también crea una instancia en user2 que tiene un valor diferente para email pero tiene los mismos valores para los campos username, active y sign_in_count de user1. Él ..user1 debe ir al final para especificar que cualquier campo restante debe obtener sus valores del campo correspondiente en user1, pero podemos elegir especificar valores para tantos campos como queramos en cualquier orden, independientemente del orden de los campos en la definición del struct.

Nota que la sintaxis de update struct usa = como una asignación; esto es porque mueve los datos, como vimos en la sección “Variables y datos interactuando con Move”. En este ejemplo, ya no podemos usar user1 como un todo después de crear user2 porque el String en el campo username de user1 se movió a user2. Si hubiéramos dado a user2 nuevos valores String para email y username, y por lo tanto solo usamos los valores de active y sign_in_count de user1, entonces user1 todavía sería válido después de crear user2. Tanto active como sign_in_count son tipos que implementan la trait Copy, por lo que el comportamiento que discutimos en la sección “Datos de pila: Copy” se aplicaría. Nosotros podemos aún usar user1.email en este ejemplo, debido a que el valor no es movido.

Usando Structs de Tuplas sin Campos Nombrados para Crear Diferentes Tipos

Rust también admite structs que se parecen a tuplas, llamados structs de tuplas. Los structs de tuplas tienen el significado adicional que proporciona el nombre del struct, pero no tienen nombres asociados a sus campos; en su lugar, solo tienen los tipos de los campos. Los structs de tuplas son útiles cuando desea darle un nombre al conjunto completo y hacer que el conjunto sea un tipo diferente de otros conjuntos, y cuando nombrar cada campo como en un struct regular sería verboso o redundante.

Para definir un struct de tupla, comience con la palabra clave struct y el nombre del struct seguido por los tipos en la tupla. Por ejemplo, aquí definimos y usamos dos structs de tupla llamados Color y Point:

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

Nota que los valores black y origin son diferentes tipos porque son instancias de diferentes structs de tupla. Cada struct que defina es su propio tipo, incluso si los campos dentro del struct tienen los mismos tipos. Por ejemplo, una función que toma un parámetro de tipo Color no puede tomar un Point como argumento, incluso si ambos tipos están compuestos por tres valores i32. De lo contrario, las instancias de structs de tupla son similares a las tuplas en que puede descomponerlas en sus piezas individuales, y puede usar un . seguido por el índice para acceder a un valor individual. A diferencia de las tuplas, las estructuras de tuplas requieren que nombre del tipo de estructura cuando las desestructuras. Por ejemplo, escribiríamos let Punto(x, y, z) = punto.

Structs de Unidad sin Campos

También puede definir structs que no tienen ningún campo. Estos se llaman structs de unidad porque se comportan de manera similar a (), el tipo de unidad que mencionamos en la sección “El tipo de tupla”. Los structs de unidad pueden ser útiles cuando necesita implementar un trait en algún tipo, pero no tiene datos que desea almacenar en el tipo propio. Discutiremos los traits en el Capítulo 10. Aquí hay un ejemplo de declarar e instanciar un struct de unidad llamado AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Para definir AlwaysEqual, usamos la palabra clave struct, el nombre que queremos y luego un punto y coma. ¡No se necesitan llaves ni paréntesis! Luego podemos obtener una instancia de AlwaysEqual en la variable subject de la misma manera: usando el nombre que definimos, sin llaves ni paréntesis. Imagina que más tarde implementaremos un comportamiento para este tipo de tal manera que cada instancia de AlwaysEqual siempre sea igual a cada instancia de cualquier otro tipo, tal vez para tener un resultado conocido para fines de prueba. No necesitaríamos ningún dato para implementar ese comportamiento. Verás en el Capítulo 10 cómo definir traits e implementarlos en cualquier tipo, incluidos los structs de unidad.

Ownership de los datos de Struct

En el struct User de la definición en el Listing 5-1, usamos el tipo String en lugar del tipo &str de la cadena de caracteres. Esta es una elección deliberada porque queremos que cada instancia de este struct tenga todos sus datos y que esos datos sean válidos durante todo el tiempo que el struct sea válido.

También es posible para los structs almacenar referencias a datos que son propiedad de algo más, pero para hacerlo requiere el uso de lifetimes, una característica de Rust que discutiremos en el Capítulo 10. Los lifetimes garantizan que los datos referenciados por un struct sean válidos durante el tiempo que el struct sea válido. Digamos que intentas almacenar una referencia en un struct sin especificar lifetimes, como el siguiente; esto no funcionará:

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

El compilador se quejará de que necesita especificadores de lifetime:

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

En el Capítulo 10, discutiremos como solucionar estos errores para que puedas almacenar referencias en structs, pero por ahora, solucionaremos los errores usando tipos propios como String en lugar de referencias como &str.

Un Programa de Ejemplo Usando Structs

Para entender cuándo podríamos querer usar structs, vamos a escribir un programa que calcule el área de un rectángulo. Empezaremos usando variables individuales, y luego refactorizaremos el programa hasta que estemos usando structs.

Hagamos un nuevo proyecto binario con Cargo llamado rectangles que tomará el ancho y el alto de un rectángulo especificado en píxeles y calculará el área del rectángulo. La lista 5-8 muestra un programa corto con una forma de hacer exactamente eso en el src/main.rs de nuestro proyecto.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

Ahora, ejecuta este programa usando cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

Este código logra calcular el área del rectángulo llamando a la función area con cada dimensión, pero podemos hacer más para hacer este código claro y legible.

El problema con este código es evidente en la firma de area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

La función area está supuestamente para calcular el área de un rectángulo, pero la función que escribimos tiene dos parámetros, y no está claro en ningún lugar de nuestro programa que los parámetros están relacionados. Sería más legible y más manejable agrupar el ancho y el alto juntos. Ya hemos discutido una forma de hacerlo en la sección “El Tipo Tupla” del Capítulo 3: usando tuplas.

Refactorizando con Tuplas

Listings 5-9 muestra otra versión de nuestro programa que usa tuplas.

fn main() {
    let rect1 = (30, 50);

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

En un sentido, este programa es mejor. Las tuplas nos permiten agregar un poco de estructura, y ahora estamos pasando solo un argumento. Pero en otro sentido, esta versión es menos clara: las tuplas no nombran sus elementos, por lo que tenemos que indexar los componentes de la tupla, haciendo que nuestro cálculo sea menos obvio.

Mezclar el ancho y el alto no importaría para el cálculo del área, pero si queremos dibujar el rectángulo en la pantalla, ¡importaría! Tendríamos que tener en cuenta que width es el índice de la tupla 0 y height es el índice de la tupla 1. ¡Esto sería aún más difícil para que otra persona lo descubriera y lo tuviera en cuenta si usara nuestro código! Debido a que no hemos transmitido el significado de nuestros datos en nuestro código, ahora es más fácil introducir errores.

Refactorizando con Structs: Añadiendo Más Significado

Hemos usado structs para agregar significado al etiquetar los datos. Podemos transformar la tupla que estamos usando en un struct con un nombre para la estructura y nombres para los campos, como se muestra en la lista 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

Hemos definido un struct y lo hemos llamado Rectangle. Dentro de las llaves, hemos definido los campos como width y height, ambos de los cuales tienen el tipo u32. Luego, en main, hemos creado una instancia particular de Rectangle que tiene un ancho de 30 y un alto de 50.

Nuestra función area ahora toma un argumento que es una referencia a una instancia de Rectangle en lugar de dos parámetros numéricos. En la función, usamos el punto para acceder a los campos de la instancia de Rectangle que recibimos como argumento. En main, creamos una instancia de Rectangle y llamamos a la función area con la instancia de Rectangle como argumento.

La función area accede a los campos de width y height de la instancia de Rectangle (tenga en cuenta que acceder a los campos de una instancia de estructura prestada no mueve los valores de los campos, por lo que a menudo ve préstamos de estructuras). Nuestra firma de función para area ahora dice exactamente lo que queremos: calcular el área de Rectangle, usando sus campos width y height. Esto conduce a que el ancho y el alto estén relacionados entre sí, y da nombres descriptivos a los valores en lugar de usar los valores de índice de tupla de 0 y 1. ¡Esto es una victoria para la claridad!

Añadiendo Funcionalidad Útil con Traits Derivados

Sería útil poder imprimir una instancia de Rectangle mientras estamos depurando nuestro programa y ver los valores de todos sus campos. La lista 5-11 intenta usar la macro println! como hemos usado en capítulos anteriores. Sin embargo, esto no funcionará.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {}", rect1);
}

Cuando compilamos este código, obtenemos un error con este mensaje principal:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

La macro println! puede hacer muchos tipos de formateo, y por defecto, las llaves curvas le dicen a println! que use el formateo conocido como Display: salida destinada al consumo directo del usuario final. Los tipos primitivos que hemos visto hasta ahora implementan Display por defecto porque solo hay una forma en que querrías mostrar un 1 u otro tipo primitivo a un usuario. Pero con las estructuras, la forma en que println! debe formatear la salida es menos clara porque hay más posibilidades de visualización: ¿Quieres comas o no? ¿Quieres imprimir las llaves curvas? ¿Deben mostrarse todos los campos? Debido a esta ambigüedad, Rust no intenta adivinar lo que queremos, y las estructuras no tienen una implementación proporcionada de Display para usar con println! y el marcador de posición {}.

Si seguimos leyendo los errores, encontraremos esta nota útil:

   = help: the trait `std::fmt::Display` is not implemented for `Rectangle`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead

Intentemos eso. La llamada a la macro println! ahora se verá así: println!("rect1 es {rect1:?}");. Poner el especificador :? dentro de los corchetes curvos le dice a println! que queremos usar un formato de salida llamado Debug. El rasgo Debug nos permite imprimir nuestra estructura de una manera que sea útil para los desarrolladores para que podamos ver su valor mientras depuramos nuestro código.

Compilamos el código con este cambio. ¡Oh, no! Todavía obtenemos un error:

error[E0277]: `Rectangle` doesn't implement `Debug`

Pero otra vez, el compilador nos da una nota útil:

   = help: the trait `Debug` is not implemented for `Rectangle`
   = note: add `#[derive(Debug)]` to `Rectangle` or manually `impl Debug for Rectangle`

Rust si incluye la funcionalidad para imprimir información de depuración, pero tenemos que optar explícitamente para hacer que esa funcionalidad esté disponible para nuestra estructura. Para hacer eso, agregamos el atributo externo #[derive(Debug)] justo antes de la definición de la estructura, como se muestra en la lista 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

Ahora, cuando compilamos el código, no obtendremos ningún error, y veremos la siguiente salida:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

¡Bien! No es la salida más bonita, pero muestra los valores de todos los campos de esta instancia, lo que definitivamente ayudaría durante la depuración. Cuando tenemos estructuras más grandes, es útil tener una salida que sea un poco más fácil de leer; en esos casos, podemos usar {:#?} en lugar de {:?} en el string println!. En este ejemplo, el uso del estilo {:#?} producirá la siguiente salida:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

Otra forma de imprimir un valor usando el formato Debug es usar la macro dbg!, que toma el ownership de una expresión (en oposición a println!, que toma una referencia), imprime el archivo y el número de línea donde se produce esa llamada a la macro dbg! en su código junto con el valor resultante de esa expresión, y devuelve el ownership del valor.

Nota: Llamar a la macro dbg! imprime en el flujo de consola de error estándar (stderr), en oposición a println!, que imprime en el flujo de consola de salida estándar (stdout). Hablaremos más sobre stderr y stdout en la sección “Escribiendo mensajes de error en el error estándar en lugar de la salida estándar” del capítulo 12.

Aquí hay un ejemplo en el que estamos interesados en el valor que se asigna al campo width, así como el valor de todo el struct en rect1:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

Podemos poner dbg! alrededor de la expresión 30 * scale y, porque dbg! devuelve el ownership del valor de la expresión, el campo width tendrá el mismo valor que si no tuviéramos la llamada dbg! allí. No queremos que dbg! tome el ownership de rect1, así que usamos una referencia a rect1 en la siguiente llamada. Aquí está el output de este ejemplo:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

Podemos ver que el primer bit de salida proviene de la linea 10 de src/main.rs donde estamos depurando la expresión 30 * scale, y su valor resultante es 60 (el formato de Debug implementado para enteros es imprimir sólo su valor). La llamada a dbg! en la línea 14 de src/main.rs produce el valor de &rect1, que es la estructura de Rectangle. Esta salida usa el formato Debug de la estructura Rectangle. La macro dbg! puede ser realmente útil cuando está tratando de averiguar qué está haciendo su código.

Además del trait Debug, Rust nos ha proporcionado un número de traits para que podamos usar con el atributo derive que pueden agregar un comportamiento útil a nuestros tipos personalizados. Esos traits y sus comportamientos se enumeran en el Apéndice C. Cubriremos cómo implementar estos traits con un comportamiento personalizado, así como cómo crear sus propios traits en el Capítulo 10. También hay muchos atributos más allá de derive; para obtener más información, consulte la sección “Atributos” de la Referencia de Rust.

Nuestra función area es muy específica: solo calcula el área de rectángulos. Sería útil vincular este comportamiento más estrechamente a nuestra estructura Rectangle porque no funcionará con ningún otro tipo. Veamos cómo podemos continuar refactorizando este código al convertir la función area en un método area definido en nuestro tipo Rectangle.

Sintaxis de Métodos

Los métodos son similares a las funciones: los declaramos con la palabra clave fn y un nombre, pueden tener parámetros y un valor de retorno, y contienen alguno código que se ejecuta cuando el método es llamado desde otro lugar. A diferencia de las funciones, los métodos se definen dentro del contexto de una estructura (o un enum o un objeto de tipo trait, que cubriremos en el Capítulo 6 y el Capítulo 17, respectivamente), y su primer parámetro siempre es self, que representa la instancia de la estructura en la que se está llamando al método.

Definiendo Metodos

Vamos a cambiar la función area que tiene una instancia de Rectangle como parámetro y en vez de eso definamos un método area en el struct Rectangle, como se muestra en el Listado 5-13.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

Para definir la función dentro del contexto de Rectangle, iniciamos un bloque impl (implementación). Todo lo que esté dentro de este bloque impl estará asociado al tipo Rectangle. Luego movemos la función area dentro de las llaves del bloque impl y cambiamos el primer (y en este caso, único) parámetro para ser self en la firma y en todas partes dentro del cuerpo. En main, donde llamamos a la función area y pasamos rect1 como argumento, podemos en vez de eso usar la sintaxis de método para llamar al método area en nuestra instancia de Rectangle. La sintaxis de método va después de una instancia: se agrega un punto seguido del nombre del método, paréntesis y cualquier argumento.

En la firma para area, usamos &self en vez de rectangle: &Rectangle. El &self es en realidad una abreviatura para self: &Self. Dentro de un bloque impl, el tipo Self es un alias para el tipo al que pertenece el bloque impl. Los métodos deben tener un parámetro llamado self de tipo Self para su primer parámetro, por lo que Rust nos permite abreviar esto con solo el nombre self en el primer parámetro. Ten en cuenta que aún necesitamos usar el & antes de la abreviatura self para indicar que este método toma prestada la instancia Self, al igual que hicimos en rectangle: &Rectangle. Los métodos pueden tomar la propiedad de self, tomarlo prestado de forma inmutable, como hemos hecho aquí, o tomarlo prestado de forma mutable, al igual que pueden hacerlo con cualquier otro parámetro.

Elegimos &self aquí por la misma razón que usamos &Rectangle en la versión de la función: no queremos tomar la propiedad, y solo queremos leer los datos en la estructura, no escribir en ella. Si quisiéramos cambiar la instancia en la que hemos llamado al método como parte de lo que el método hace, usaríamos &mut self como primer parámetro. Tener un método que tome la propiedad de la instancia usando solo self como primer parámetro es raro; esta técnica se usa normalmente cuando el método transforma self en otra cosa y quieres evitar que el que llama al método use la instancia original después de la transformación.

La razón principal para usar métodos en vez de funciones, además de proveer la sintaxis de método y no tener que repetir el tipo de self en cada firma de método, es para la organización. Hemos puesto todas las cosas que podemos hacer con una instancia de un tipo en un bloque impl en vez de hacer que los usuarios futuros de nuestro código busquen las capacidades de Rectangle en varios lugares en la biblioteca que proveemos.

Nota que podemos elegir darle al método el mismo nombre que uno de los campos del struct. Por ejemplo, podemos definir un método en Rectangle que se llame width:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

Aquí, estamos eligiendo que el método width retorne true si el valor en el campo width de la instancia es mayor que 0 y false si el valor es 0: podemos usar un campo dentro de un método del mismo nombre para cualquier propósito. En main, cuando seguimos rect1.width con paréntesis, Rust sabe que queremos decir el método width. Cuando no usamos paréntesis, Rust sabe que queremos decir el campo width.

A veces, pero no siempre, cuando damos un método el mismo nombre que un campo queremos que solo retorne el valor en el campo y no haga nada más. Los métodos como este se llaman getters, y Rust no los implementa automáticamente para los campos de un struct como lo hacen otros lenguajes. Los getters son útiles porque puedes hacer que el campo sea privado, pero el método sea público, y así permitir acceso de solo lectura a ese campo como parte de la API pública del tipo. Hablaremos de qué es público y privado y cómo designar un campo o método como público o privado en el Capítulo 7.

¿Donde esta el Operador ->?

En C y C++, se usan dos operadores diferentes para llamar a métodos: se usa . si se está llamando a un método en el objeto directamente y -> si se está llamando al método en un puntero al objeto y se necesita desreferenciar el puntero primero. En otras palabras, si object es un puntero, object->something() es similar a (*object).something().

Rust no tiene un equivalente al operador ->; en su lugar, Rust tiene una característica llamada referenciación y desreferenciación automáticas. Llamar a métodos es uno de los pocos lugares en Rust donde se tiene este comportamiento.

Así es como funciona: cuando llamas a un método con object.something(), Rust automáticamente agrega &, &mut, o * para que object coincida con la firma del método. En otras palabras, lo siguiente es lo mismo:

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

El primer ejemplo es más limpio. Este comportamiento de referencia y desreferenciación automática funciona porque los métodos tienen un receptor claro: el tipo de self. Dado el receptor y el nombre de un método, Rust puede determinar con certeza si el método está leyendo (&self), mutando (&mut self), o consumiendo (self). El hecho de que Rust haga que el préstamo sea implícito para los receptores de método es una gran parte de hacer que la propiedad sea ergonómica en la práctica.

Métodos con más parámetros

Practiquemos usando métodos implementando un segundo método en la estructura Rectangle. Esta vez queremos que una instancia de Rectangle tome otra instancia de Rectangle y retorne true si el segundo Rectangle puede completamente caber dentro de self (el primer Rectangle); de lo contrario, debería retornar false. Es decir, una vez que hayamos definido el método can_hold, queremos poder escribir el programa mostrado en el Listing 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

La salida esperada se vería como la siguiente porque ambas dimensiones de rect2 son más pequeñas que las dimensiones de rect1, pero rect3 es más ancha que rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

Sabemos que queremos definir un método, por lo que estará dentro del bloque impl Rectangle. El nombre del método será can_hold, y tomará un préstamo inmutable de otro Rectangle como parámetro. Podemos decir cuál será el tipo del parámetro mirando el código que llama al método: rect1.can_hold(&rect2) pasa &rect2, que es un préstamo inmutable a rect2, una instancia de Rectangle. Esto tiene sentido porque solo necesitamos leer rect2 (en lugar de escribir, lo que significaría que necesitaríamos un préstamo mutable), y queremos que main conserve la propiedad de rect2 para que podamos usarlo nuevamente después de llamar al método can_hold. El valor de retorno de can_hold será un Booleano, y la implementación verificará si el ancho y alto de self son mayores que el ancho y alto del otro Rectangle, respectivamente. Agreguemos el nuevo método can_hold al bloque impl del Listing 5-13 que se muestra en el Listing 5-15.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

Cuando ejecutamos este código con la función main en el Listing 5-14, obtendremos el resultado deseado. Los métodos pueden tomar múltiples parámetros que agregamos a la firma después del parámetro self, y esos parámetros funcionan igual que los parámetros en las funciones.

Funciones asociadas

Todas las funciones definidas dentro de un bloque impl se llaman funciones asociadas porque están asociadas con el tipo nombrado después del impl. Podemos definir funciones asociadas que no tengan self como su primer parámetro (y, por lo tanto, no sean métodos) porque no necesitan una instancia del tipo con el que trabajar. Ya hemos usado una función como esta: la función String::from que está definida en el tipo String.

Las funciones asociadas que no son métodos son a menudo utilizadas para constructores que devolverán una nueva instancia de la estructura. Estás a menudo se llaman new, pero new no es un nombre especial y no está incorporado en el lenguaje. Por ejemplo, podríamos elegir proporcionar una función asociada llamada square que tendría un parámetro de dimensión y lo usaría como ancho y alto, de modo que sea más fácil crear un Rectangle cuadrado en lugar de tener que especificar el mismo valor dos veces:

Filename: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

La palabra clave Self en el tipo de retorno y en el cuerpo de la función es un alias para el tipo que aparece después de la palabra clave impl, que en este caso es Rectangle.

Para llamar a esa función asociada, usamos la sintaxis :: con el nombre de la estructura; let sq = Rectangle::square(3); es un ejemplo. Esta función está dentro del namespace de la estructura. La sintaxis :: se usa tanto para las funciones asociadas como para los namespaces creados por los módulos. Discutiremos los módulos en el Capítulo 7.

Bloques impl múltiples

Cada struct es permitido tener múltiples bloques impl. Por ejemplo, el Listing 5-15 es equivalente al código mostrado en el Listing 5-16, que tiene cada método en su propio bloque impl.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

No hay razón para separar estos métodos en múltiples bloques impl aquí, pero esta es una sintaxis válida. Veremos un caso en el que los múltiples bloques impl son útiles en el Capítulo 10, donde discutiremos los tipos genéricos y los traits.

Resumen

Los structs te permiten crear tipos personalizados que son significativos para su dominio. Al usar structs, puede mantener piezas de datos asociadas entre sí y nombrar cada pieza para hacer que su código sea claro. En los bloques impl, puede definir funciones que están asociadas con su tipo, y los métodos son un tipo de función asociada que le permite especificar el comportamiento que tienen las instancias de sus structs.

Pero los structs no son la única forma de crear tipos personalizados: pasemos a la función enum de Rust para agregar otra herramienta a su toolbox.

Enums y Pattern Matching

En este capítulo, vamos a ver las enumeraciones, también conocidos como enums. Los enums te permiten definir un tipo enumerando sus posibles variantes. Primero definiremos y usaremos un enum para mostrar cómo un enum puede codificar el significado junto con datos. A continuación, exploraremos un enum particularmente útil, llamado Option, que expresa que un valor puede ser algo o nada. Luego veremos cómo el patrón de coincidencia en la expresión match hace que sea fácil ejecutar un código diferente para diferentes valores de un enum. Finalmente, veremos cómo la construcción if let es otra expresión conveniente y concisa disponible para manejar enums en su código.

Definiendo un Enum

Los struct te permiten agrupar campos relacionados y datos, como un Rectángulo con su ancho y largo. Por otro lado, los enums te permiten decir que un valor es uno de un conjunto de posibles valores. Por ejemplo, podríamos querer decir que Rectángulo es uno de un conjunto de posibles formas que también incluye Circulo y Triangulo. Para hacer esto, Rust nos permite codificar estas posibilidades como un enum.

Vamos a ver una situación que podemos expresar en código y veremos por qué los enums son útiles y más apropiados que los structs en este caso. Digamos que tenemos que trabajar con direcciones IP. Actualmente, existen dos estándares que se usan para direcciones IP: la versión cuatro y la versión seis. Como estos son los únicos posibles tipos de direcciones IP que nuestro programa encontrará, podemos enumerar todas las variantes posibles, de donde viene el nombre de enum.

Cualquier dirección IP puede ser una dirección de la versión cuatro o la versión seis, pero no ambas al mismo tiempo. Esa propiedad de las direcciones IP hace que la estructura de datos enum sea apropiada porque un valor enum puede ser sólo una de sus variantes. Tanto las direcciones de la versión cuatro como la versión seis siguen siendo fundamentalmente direcciones IP, por lo que deben ser tratadas como el mismo tipo cuando el código está manejando situaciones que se aplican a cualquier tipo de dirección IP.

Podemos expresar este concepto en código definiendo el enum IpAddrKind y enumerando los posibles tipos de direcciones IP, V4 y V6. Estas son las variantes del enum:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind ahora es un tipo de datos personalizado que podemos usar en otras partes de nuestro código.

Valores Enum

Podemos crear instancias de cada una de las dos variantes de IpAddrKind de esta manera:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Nota que las variantes del enum están en el mismo espacio de nombres bajo su identificador, y usamos dos puntos para separar los dos. Esto es útil porque ahora ambos valores IpAddrKind::V4 e IpAddrKind::V6 son del mismo tipo: IpAddrKind. Podemos entonces, por ejemplo, definir una función que tome cualquier IpAddrKind:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Y podemos llamar a esta función con cualquiera de las variantes:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

Usando enum tiene aún más ventajas. Pensando más en nuestro tipo de dirección IP, en este momento no tenemos una forma de almacenar los datos reales de la dirección IP; solo sabemos qué tipo es. Dado que acabas de aprender sobre los structs en el Capítulo 5, podrías estar tentado a abordar este problema con structs como se muestra en el Listing 6-1.

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

Aquí, hemos definido un struct IpAddr que tiene dos campos: un campo kind que es de tipo IpAddrKind (el enum que definimos anteriormente) y un campo address de tipo String. Tenemos dos instancias de este struct. La primera es home, y tiene el valor IpAddrKind::V4 como su kind como datos de dirección asociados de 127.0.0.1. La segunda instancia es loopback. Tiene la otra variante de IpAddrKind como su valor kind, V6, y tiene la dirección ::1 asociada con ella. Hemos usado un struct para agrupar los valores kind y address juntos, así que ahora la variante está asociada con el valor.

Sin embargo, representar el mismo concepto usando sólo un enum es más conciso: en lugar de un enum dentro de un struct, podemos poner datos directamente en cada variante de enum. Esta nueva definición del enum IpAddr dice que tanto las variantes V4 como V6 tendrán valores String asociados:

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

Adjuntamos datos a cada variante del enum directamente, por lo que no hay necesidad de un struct extra. Aquí, también es más fácil ver otro detalle de cómo funcionan los enums: el nombre de cada variante de enum que definimos también se convierte en una función que construye una instancia del tipo enum. Es decir, IpAddr::V4() es una llamada a función que toma un argumento String y devuelve una instancia del tipo IpAddr. Obtenemos automáticamente esta función constructora definida como resultado de definir el enum.

Hay otra ventaja de usar un enum en lugar de un struct: cada variante puede tener diferentes tipos y cantidades de datos asociados con ella. La versión cuatro de las direcciones IP siempre tendrá cuatro componentes numéricos que tendrán valores entre 0 y 255. Si quisiéramos almacenar las direcciones V4 como cuatro valores u8 pero aun así expresar las direcciones V6 como un valor String, no podríamos hacerlo con un struct. Los enums manejan este caso con facilidad:

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

Hemos mostrado varias formas diferentes de definir estructuras de datos para almacenar direcciones IP de la versión cuatro y de la versión seis. Sin embargo, resulta que querer almacenar direcciones IP y codificar de que tipo son es tan común que la biblioteca estándar tiene una definición que podemos usar! Veamos cómo define la biblioteca estándar IpAddr: tiene el enum exacto y las variantes que hemos definido y usado, pero incrusta los datos de dirección dentro de las variantes en forma de dos structs diferentes, que se definen de manera diferente para cada variante:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

Este código ilustra que puedes poner cualquier tipo de datos dentro de una variante de enum: strings, tipos numéricos o structs, por ejemplo. ¡Incluso puedes incluir otro enum! Además, los tipos de biblioteca estándar a menudo no son mucho más complicados de lo que podrías idear.

Ten en cuenta que aunque la biblioteca estándar contiene una definición para IpAddr, aún podemos crear y usar nuestra propia definición sin conflicto porque no hemos traído la definición de la biblioteca estándar a nuestro contexto de ejecución. Hablaremos más sobre cómo traer tipos al contexto de ejecución en el Capítulo 7.

Veamos otro ejemplo de una enumeración en el Listing 6-2: este tiene una amplia variedad de tipos incrustados en sus variantes.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

Este enum tiene cuatro variantes con diferentes tipos:

• Quit no tiene ningún dato asociado.
• Move tiene campos nombrados, como lo haría un struct.
• Write incluye un solo String.
• ChangeColor incluye tres valores i32.

Definiendo un enum con variantes como las del Listing 6-2 es similar a definir diferentes tipos de definiciones de struct, excepto que el enum no use la palabra clave struct y todas las variantes están agrupadas juntas bajo el tipo Message. Los siguientes structs podrían contener los mismos datos que las variantes de enum anteriores:

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

Pero si usamos los diferentes structs, cada uno de los cuales tiene su propio tipo, no podríamos definir tan fácilmente una función para tomar cualquiera de estos tipos de mensajes como podríamos con el enum Message definido en el Listing 6-2, que es un solo tipo.

Hay una similitud entre enums y structs que puede ser útil de recordar: al igual que puedes definir métodos en structs usando impl, puedes definir métodos en enums. Aquí hay un método llamado call que podemos definir en nuestro enum Message:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

El cuerpo del método usaría self para obtener el valor en el que llamamos el método. En este ejemplo, hemos creado una variable m que tiene el valor Message::Write(String::from("hello")), y eso es lo que será self en el cuerpo del método call cuando se ejecute m.call().

Veamos otro enum en la librería estándar que es muy común y útil: Option.

El Enum Option y Sus Ventajas Sobre los Valores Null

Esta sección explora un caso de estudio de Option, que es otro enum definido por la biblioteca estándar. El tipo Option codifica el escenario muy común en el que un valor podría ser algo o podría ser nada.

Por ejemplo, si solicita el primer elemento de una lista no vacía, obtendría un valor. Si solicita el primer elemento de una lista vacía, no obtendría nada. Expresar este concepto en términos del sistema de tipos significa que el compilador puede verificar si ha manejado todos los casos que debería estar manejando; esta funcionalidad puede prevenir errores que son extremadamente comunes en otros lenguajes de programación.

El diseño del lenguaje de programación a menudo se piensa en términos de qué características se incluyen, pero las características que se excluyen son importantes también. Rust no tiene la característica de null que muchos otros lenguajes tienen. Null es un valor que significa que no hay ningún valor allí. En los lenguajes con null, las variables siempre pueden estar en uno de dos estados: null o no null.

En su presentación del 2009 “Null References: The Billion Dollar Mistake”, Tony Hoare, el inventor de null, tiene esto que decir:

Llámalo mi error de un billón de dólares. En ese momento, estaba diseñando el primer sistema de tipos completo para referencias en un lenguaje de programación orientado a objetos. Mi objetivo era asegurarme de que todo el uso de referencias fuera absolutamente seguro, con verificación realizada automáticamente por el compilador. Pero no pude resistir la tentación de poner un valor null, simplemente porque era tan fácil de implementar. Esto a dado lugar a innumerables errores, vulnerabilidades y bloqueos del sistema, que probablemente han causado un billón de dólares de dolor y daños en los últimos cuarenta años.

El problema con los valores null es que si intentas utilizar un valor null como un valor no null, obtendrás un error de algún tipo. Debido a que esta propiedad nula o no nula es omnipresente, es extremadamente fácil cometer este tipo de error.

Sin embargo, el concepto que null está tratando de expresar sigue siendo útil: un null es un valor que es actualmente inválido o ausente por alguna razón.

El problema no es realmente con el concepto, sino con la implementación particular. Como tal, Rust no tiene null, pero tiene un enum que puede codificar el concepto de un valor presente o ausente. Este enum es Option<T>, y está definido por la biblioteca estándar de la siguiente manera:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

El enum Option<T> es tan útil que incluso está incluido en el prelude; no necesitas traerlo al contexto de ejecución explícitamente. Sus variantes también están incluidas en el prelude: puedes usar Some y None directamente sin el prefijo Option::. El enum Option<T> es aún un enum regular, y Some(T) y None son aún variantes de tipo Option<T>.

La sintaxis <T> es una característica de Rust que aún no hemos hablado. Es un parámetro de tipo genérico, y cubriremos los genéricos en más detalle en el Capítulo 10. Por ahora, todo lo que necesitas saber es que <T> significa que la variante Some del enum Option puede contener una pieza de datos de cualquier tipo, y que cada tipo concreto que se usa en lugar de T hace que el tipo Option<T> general sea un tipo diferente. Aquí hay algunos ejemplos de usar valores Option para contener tipos de números y tipos de strings:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

El tipo de some_number es Option<i32>. El tipo de some_string es Option<String>, que es un tipo diferente. Rust puede inferir estos tipos porque hemos especificado un valor dentro de la variante Some. Para absent_number, Rust requiere que anotemos el tipo general Option: el compilador no puede inferir el tipo que tendrá la variante Some correspondiente mirando sólo un valor None. Aquí, le decimos a Rust que queremos que absent_number sea del tipo Option<i32>.

Cuando tenemos un valor Some, sabemos que un valor está presente y el valor se mantiene dentro del Some. Cuando tenemos un valor None, en cierto sentido significa lo mismo que null: no tenemos un valor válido. Entonces, ¿por qué tener Option<T> es mejor que tener null?

En resumen, porque Option<T> y T (donde T puede ser cualquier tipo) son tipos diferentes, el compilador no nos permitirá usar un valor Option<T> como si fuera definitivamente un valor válido. Por ejemplo, este código no se compilará, porque está tratando de agregar un i8 a un Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

Si ejecutamos este código, obtenemos un mensaje de error como este:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&'a i8` implements `Add<i8>`
            `&i8` implements `Add<&i8>`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `enums` (bin "enums") due to 1 previous error

¡Intenso! En efecto, este mensaje de error significa que Rust no entiende cómo agregar un i8 y un Option<i8>, porque son tipos diferentes. Cuando tenemos un valor de un tipo como i8 en Rust, el compilador se asegurará de que siempre tengamos un valor válido. Podemos proceder con confianza sin tener que comprobar si es null antes de usar ese valor. Solo cuando tenemos un Option<i8> (o el tipo de valor que estemos trabajando) tenemos que preocuparnos por posiblemente no tener un valor, y el compilador se asegurará de que manejemos ese caso antes de usar el valor.

En otras palabras, tienes que convertir un Option<T> a un T antes de que puedas realizar operaciones T con él. Generalmente, esto ayuda a detectar uno de los errores más comunes con null: asumiendo que algo no es null cuando realmente lo es.

Eliminar el riesgo de asumir incorrectamente un valor no null ayuda a tener más confianza en su código. Para tener un valor que posiblemente pueda ser null, debe optar explícitamente por hacer que el tipo de ese valor sea Option<T>. Entonces, cuando use ese valor, se le requerirá expresar explícitamente el caso cuando el valor es null. Siempre que un valor tenga un tipo que no sea Option<T>, se puede asumir con seguridad que el valor no es null. Esta fue una decisión deliberada del diseño de Rust para limitar la omnipresencia de nulls y aumentar la seguridad del código de Rust.

Entonces ¿cómo obtienes el valor T de un Some cuando tienes un valor de tipo Option<T> para que puedas usar ese valor? El enum Option<T> tiene una gran cantidad de métodos que son útiles en una variedad de situaciones; puedes verlos en su documentación. Familiarizarse con los métodos en Option<T> será extremadamente útil en su viaje con Rust.

En general, para usar un valor Option<T>, querrás tener código que maneje cada variante. Quieres tener algún código que se ejecute solo cuando tienes un valor Some(T), y este código está permitido de usar el T interno. Quieres tener algún otro código que se ejecute solo si tienes un valor None, y ese código no tiene un valor T disponible. La expresión match es una construcción de flujo de control que hace exactamente esto cuando se usa con enums: ejecutará diferente código dependiendo de la variante del enum que tenga, y ese código puede usar los datos dentro del valor que coincida.

El operador de control de flujo match

Rust tiene una construcción de flujo de control extremadamente poderosa llamada match que te permite comparar un valor contra una serie de patrones y luego ejecutar código basado en qué patrón coincide. Los patrones pueden estar compuestos de valores literales, nombres de variables, comodines y muchas otras cosas; El Capítulo 19 cubre todos los diferentes tipos de patrones y lo que hacen. El poder de match viene de la expresividad de los patrones y el hecho de que el compilador confirma que se tratan todos los casos posibles.

Piensa en una expresión match como una máquina de clasificación de monedas: las monedas deslizan a lo largo de una pista con orificios de diversos tamaños a lo largo de ella, y cada moneda cae a través del primer orificio que encuentra que se ajusta a ella. De la misma manera, los valores pasan a través de cada patrón en un match, y en el primer patrón en el que el valor “se ajusta”, el valor cae en el bloque de código asociado para ser utilizado durante la ejecución.

Hablando de monedas, ¡usémoslas como un ejemplo usando match! Podemos escribir una función que tome una moneda desconocida de los Estados Unidos y, de una manera similar a la máquina de conteo, determine qué moneda es y devuelva su valor en centavos, como se muestra en el Listing 6-3.

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Desglosemos el uso de match en la función value_in_cents. Primero listamos la palabra clave match seguida de una expresión, que en este caso es el valor coin. Esto parece muy similar a una expresión condicional utilizada con if, pero hay una gran diferencia: con if, la condición debe evaluar a un valor Booleano, pero aquí puede ser cualquier tipo. El tipo de coin en este ejemplo es el enum Coin que definimos en la primera línea.

A continuación, dentro de las llaves de match, hay un número de Opciones. Una Opción tiene dos partes: un patrón y algún código. La primera Opción aquí tiene un patrón que es el valor Coin::Penny y luego el operador => que separa el patrón y el código a ejecutar. El código en este caso es solo el valor 1. Cada Opción está separado del siguiente con una coma.

Cuando la expresión match se ejecuta, compara el valor resultante contra el patrón de cada Opción, en orden. Si un patrón coincide con el valor, se ejecuta el código asociado con ese patrón. Si ese patrón no coincide con el valor, la ejecución continúa en la siguiente Opción, como en una máquina de clasificación de monedas. Podemos tener tantas Opciones como necesitemos: en el Listado 6-3, nuestro match tiene cuatro Opciones.

El código asociado con cada Opción es una expresión, y el valor resultante de la expresión en la Opción coincidente es el valor que se devuelve para la expresión match completa.

Por lo general, no usamos llaves si el código de la Opción de match es corto, como lo es en el Listado 6-3, donde cada Opción solo devuelve un valor. Si desea ejecutar varias líneas de código en una Opción de match, debe usar llaves, y la coma que sigue a la Opción es opcional. Por ejemplo, el siguiente código imprime “¡Moneda de la suerte!” cada vez que el método se llama con un Coin::Penny, pero aún devuelve el último valor del bloque, 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

Patrones que vinculan valores

Otra característica útil de las Opciones de match es que pueden vincularse a las partes del valor que coinciden con el patrón. Esto es cómo podemos extraer valores de las variantes de enum.

Como ejemplo, podemos cambiar el código de la función value_in_cents para que, en lugar de devolver un valor, imprima el valor que tiene. Esto nos permite ver qué moneda tenemos y cuánto vale. Para hacer esto, necesitamos convertir el código de cada Opción en una expresión, y luego usar una expresión println! en lugar de un valor de retorno. También necesitamos cambiar el tipo de value_in_cents a (), ya que no estamos devolviendo un valor entero, sino que estamos ejecutando código. El código completo se muestra en el Listing 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

Imaginemos que tenemos un amigo que está tratando de coleccionar todas las monedas de 50 estados. Mientras clasificamos nuestra moneda suelta por tipo de moneda, también llamaremos al nombre del estado asociado con cada moneda de 50 centavos para que si es uno que no tiene, pueda agregarlo a su colección.

En la expresión match en el Listado 6-4, podemos agregar UsState::Alaska a la variante Coin::Quarter para crear una nueva variante de Coin. Cuando hacemos esto, el estado de Alaska se adjunta a la moneda. Luego, cuando ejecutamos el código, podemos ver el valor del estado almacenado en la moneda de 50 centavos al imprimirlo. El código completo se muestra en el Listing 6-5.

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

Si llamáramos a value_in_cents(Coin::Quarter(UsState::Alaska)), coin sería Coin::Quarter(UsState::Alaska). Cuando comparamos ese valor con cada una de las Opciones de match, ninguno coincide hasta que llegamos a Coin::Quarter(state). En ese punto, el enlace para state será el valor UsState::Alaska. Luego podemos usar ese enlace en la expresión println!, obteniendo así el valor del estado interno de la variante de Coin para Quarter.

Match con Option<T>

En la sección anterior, queríamos obtener el valor interno T de la variante Some cuando se usaba Option<T>; también podemos manejar Option<T> usando match, como lo hicimos con el enum Coin! En lugar de comparar monedas, compararemos las variantes de Option<T>, pero la forma en que funciona la expresión match sigue siendo la misma.

Digamos que queremos escribir una función que tome un Option<i32> y, si hay un valor dentro, agregue 1 a ese valor. Si no hay un valor dentro, la función debe devolver el valor None y no intentar realizar ninguna operación.

Esta función es muy fácil de escribir, gracias a match, y se verá como el Listing 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Examinemos la primera ejecución de plus_one en más detalle. Cuando llamamos a plus_one(five), la variable x en el cuerpo de plus_one tendrá el valor Some(5). Luego comparamos eso contra cada Opción de match:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

El valor Some(5) no coincide con el patrón None, por lo que seguimos a la siguiente Opción:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

¿Coincide Some(5) con Some(i)? ¡Lo hace! Tenemos la misma variante. Él i se vincula al valor contenido en Some, por lo que i toma el valor 5. Luego se ejecuta el código en la Opción de match, por lo que agregamos 1 al valor de i y creamos un nuevo valor Some con nuestro total 6 dentro.

Ahora consideremos la segunda llamada a plus_one en el Listing 6-5, donde x es None. Entramos en el match y comparamos con la primera Opción:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

¡Coincide! No hay valor para agregar, por lo que el programa se detiene y devuelve el valor None en el lado derecho de =>. Debido a que la primera Opción coincidió, no se comparan otras Opciones.

Combinando match y enums es útil en muchas situaciones. Verás este patrón mucho en el código Rust: match contra un enum, vincula una variable a los datos internos y luego ejecuta el código en función de él. Es un poco complicado al principio, pero una vez que te acostumbras, desearás tenerlo en todos los lenguajes. Es consistentemente un favorito de los usuarios.

Los matches son exhaustivos

Hay otro aspecto de match que debemos discutir: los patrones de las Opciones deben cubrir todas las posibilidades. Considera esta versión de nuestra función plus_one, que tiene un error y no se compila:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

No manejamos el caso None, por lo que este código causará un error. Afortunadamente, es un error que Rust sabe cómo detectar. Si intentamos compilar este código, obtendremos este error:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
   --> src/main.rs:3:15
    |
3   |         match x {
    |               ^ pattern `None` not covered
    |
note: `Option<i32>` defined here
   --> file:///home/.rustup/toolchains/1.82/lib/rustlib/src/rust/library/core/src/option.rs:571:1
    |
571 | pub enum Option<T> {
    | ^^^^^^^^^^^^^^^^^^
...
575 |     None,
    |     ---- not covered
    = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
    |
4   ~             Some(i) => Some(i + 1),
5   ~             None => todo!(),
    |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` (bin "enums") due to 1 previous error

Rust sabe que no cubrimos todos los casos posibles, e incluso sabe qué patrón olvidamos! Los matches en Rust son exhaustivos: debemos agotar todas las posibilidades para que el código sea válido. Especialmente en el caso de Option<T>, cuando Rust nos impide olvidar manejar el caso None, nos protege de asumir que tenemos un valor cuando podríamos tener nulo, haciendo así imposible el error de mil millones de dólares discutido anteriormente.

Patrones de captura y el Placeholder _

Usando enums, también podemos tomar acciones especiales para algunos valores particulares, pero para todos los demás valores, tomar una acción predeterminada. Imagina que estamos implementando un juego donde, si sacas un 3 en un lanzamiento de dados, tu jugador no se mueve, sino que obtiene un nuevo sombrero elegante. Si sacas un 7, tu jugador pierde un sombrero elegante. Para todos los demás valores, tu jugador se mueve esa cantidad de espacios en el tablero de juego. Aquí hay un match que implementa esa lógica, con el resultado del lanzamiento de dados codificado en lugar de un valor aleatorio, y toda la lógica representada por funciones sin cuerpos porque implementarlas realmente está fuera del alcance de este ejemplo:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

Para las primeras dos Opciones, los patrones son los valores literales 3 y 7. Para la última Opción que cubre cualquier otro valor posible, el patrón es la variable que hemos elegido para nombrar other. El código que se ejecuta para la Opción other usa la variable pasándola a la función move_player.

Este código compila, aunque no hemos enumerado todos los posibles valores que puede tener un u8, porque el último patrón coincidirá con todos los valores no especificados específicamente. Este patrón de captura cumple con el requisito de que match debe ser exhaustivo. Ten en cuenta que tenemos que poner la Opción de captura al final porque los patrones se evalúan en orden. Si ponemos la Opción de captura antes, las otras Opciones nunca se ejecutarían, por lo que Rust nos advertirá si agregamos Opciones después de un catch-all!

Rust también tiene un patrón que podemos usar cuando queremos un catch-all, pero no queremos usar el valor en el patrón catch-all: _ es un patrón especial que coincide con cualquier valor y no se vincula a ese valor. Esto le dice a Rust que no vamos a usar el valor, por lo que Rust no nos advertirá sobre una variable no utilizada.

Vamos a cambiar las reglas del juego. Ahora, si sacas un número diferente de un 3 o un 7 debes tirar de nuevo. Ya no necesitamos usar el valor general, por lo que puede cambiar nuestro código para usar _ en lugar de la variable llamada other:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

Este ejemplo también cumple con el requisito de exhaustividad porque estamos explícitamente ignorando todos los demás valores en la última Opción; no hemos olvidado nada.

Finalmente, cambiaremos las reglas del juego una vez más para que nada más ocurra en tu turno si sacas algo que no sea un 3 o un 7. Podemos expresar eso usando el valor de unidad (el tipo de tupla vacía que mencionamos en “El tipo de tupla” sección) como el código que va con la Opción _:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

Aquí, le decimos a Rust explícitamente que no vamos a usar ningún otro valor que no coincida con un patrón en una Opción anterior, y no queremos ejecutar ningún código en este caso.

Hay más sobre patrones y coincidencias que cubriremos en el Capítulo 19. Por ahora, vamos a pasar a la sintaxis if let que puede ser útil en situaciones en las que la expresión match es un poco larga.

Flujo de Control Conciso con if let

La sintaxis if let te permite combinar if y let en una forma menos verbosa de manejar valores que coinciden con un patrón mientras se ignoran el resto. Considera el programa en el Listado 6-6 que coincide con un valor Option<u8> en la variable config_max pero solo quiere ejecutar el código si el valor es la variante Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

Si el valor es Some, imprimimos el valor en la variante Some vinculando el valor a la variable max en el patrón. No queremos hacer nada con el valor None. Para satisfacer la expresión match, tenemos que agregar _ => () después de procesar solo una variante, lo cual es un código de plantilla molesto para agregar.

En su lugar, podríamos escribir esto de una manera más corta usando if let. El siguiente código se comporta de la misma manera que el match en el Listado 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

La sintaxis if let toma un patrón y una expresión separados por un signo igual. Funciona de la misma manera que un match, donde la expresión se da al match y el patrón es su primer brazo. En este caso, el patrón es Some(max), y el max se vincula al valor dentro del Some. Luego podemos usar max en el cuerpo del bloque if let de la misma manera que usamos max en el brazo match correspondiente. El código en el bloque if let solo se ejecuta si el valor coincide con el patrón.

Usar if let significa menos escritura, menos indentación y menos código repetitivo. Sin embargo, pierdes la verificación exhaustiva que hace cumplir match. Elegir entre match e if let depende de lo que estés haciendo en tu situación particular y de si ser más conciso a cambio de la verificación exhaustiva es un intercambio adecuado.

En otras palabras, puedes pensar en if let como una sintaxis dulce para un match que ejecuta código cuando el valor coincide con un patrón y luego ignora todos los demás valores.

Podemos incluir un else con un if let. El bloque de código que va con el else es el mismo que el bloque de código que iría con el caso _ en la expresión match que es equivalente al if let y else. Recuerda la definición de Coin en el Listado 6-4, donde la variante Quarter también tenía un valor UsState. Si quisiéramos contar todas las monedas que no son cuartos que vemos mientras también anunciamos el estado de los cuartos, podríamos hacerlo con una expresión match, como esta:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

O podríamos usar un if let y else:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

Si se encuentra en una situación en la cual tu programa tiene lógica que es demasiado verbosa para expresar usando un match, recuerda que if let está en tu caja de herramientas de Rust también.

Resumen

Ahora hemos cubierto cómo usar enums para crear tipos personalizados que pueden ser uno de un conjunto de valores enumerados. Hemos mostrado cómo el tipo Option<T> de la biblioteca estándar te ayuda a usar el sistema de tipos para prevenir errores. Cuando los valores de enum tienen datos dentro de ellos, podemos usar match o if let para extraer y usar esos valores, dependiendo de cuántos casos necesites manejar.

Tus programas Rust ahora pueden expresar conceptos en tu dominio usando structs y enums. Crear tipos personalizados para usar en tu API asegura la seguridad de tipos: el compilador se asegurará de que tus funciones solo obtengan valores del tipo que cada función espera.

En orden de proveer una API bien organizada a tus usuarios que sea sencilla de usar y solo exponga exactamente lo que tus usuarios necesitarán, ahora vamos a ver los módulos de Rust.

Administrando proyectos en crecimiento con paquetes, crates y módulos

A medida que escribes programas grandes, organizar tu código se volverá cada vez más importante. Al agrupar funcionalidades relacionadas y separar el código con características distintas, tendrás más claro dónde encontrar el código que implementa una característica concreta y dónde ir para cambiar el funcionamiento de una característica.

Los programas que hemos escrito hasta ahora han estado en un módulo en un archivo. A medida que un proyecto crece, debes organizar el código dividiéndolo en múltiples módulos y luego en múltiples archivos. Un paquete puede contener múltiples crates binarios y opcionalmente un crate de biblioteca. A medida que un paquete crece, puedes extraer partes en crates separados que se convierten en dependencias externas. Este capítulo cubre todas estas técnicas. Para proyectos muy grandes que comprenden un conjunto de paquetes interrelacionados que evolucionan juntos, Cargo proporciona workspaces, que cubriremos en la sección “Cargo Workspaces” en el Capítulo 14.

También discutiremos la encapsulación de detalles de implementación, que le permite reutilizar el código a un nivel superior: una vez que ha implementado una operación, otro código puede llamar a su código a través de su interfaz pública sin tener que saber cómo funciona la implementación. La forma en que escribes el código define qué partes son públicas para que otro código las use y qué partes son detalles de implementación privados que te reservas el derecho de cambiar. Esta es otra forma de limitar la cantidad de detalles que tienes que mantener en tu cabeza.

Un concepto relacionado es el ámbito: el contexto anidado en el que se escribe el código tiene un conjunto de nombres que se definen como "en el ámbito". Al leer, escribir y compilar código, los programadores y compiladores necesitan saber si un nombre concreto en un punto determinado se refiere a una variable, función, estructura, enumeración, módulo, constante u otro elemento, y qué significa ese elemento. Se pueden crear ámbitos y cambiar los nombres que están dentro o fuera de ellos. No puede haber dos elementos con el mismo nombre en el mismo ámbito; existen herramientas para resolver conflictos de nombres.

Rust tiene una serie de características que te permiten administrar la organización de tu código, incluidos los detalles que se exponen, los detalles que son privados y los nombres que están en cada ámbito en tus programas. Estas características, a veces denominadas colectivamente sistema de módulos, incluyen:

• Paquetes: Una característica de Cargo que te permite construir, probar y compartir crates
• Crates: Un árbol de módulos que produce una biblioteca o ejecutable
• Módulos y use: Te permiten controlar la organización, el ámbito y la privacidad de las rutas
• Rutas: Una forma de nombrar un elemento, como una estructura, función o módulo

En este capítulo, cubriremos todas estas características, discutiremos cómo interactúan y explicaremos cómo usarlas para administrar el ámbito. Al final, deberías tener una comprensión sólida del sistema de módulos y poder trabajar con ámbitos como un profesional!

Paquetes y Crates

Las primeras partes del sistema de módulos que cubriremos son los paquetes y los crates.

Un crate es la cantidad más pequeña de código que el compilador Rust considera a la vez. Incluso si ejecutas rustc en lugar de cargo y pasas un solo archivo de código fuente (como lo hicimos en la sección “Escribir y Ejecutar un Programa Rust” del Capítulo 1), el compilador considera que ese archivo es un crate. Los crates pueden contener módulos, y los módulos pueden definirse en otros archivos que se compilan con el crate, como veremos en las próximas secciones.

Un crate puede venir en una de dos formas: un crate binario o un crate de biblioteca. Los crates binarios son programas que puedes compilar a un ejecutable que puedes ejecutar, como un programa de línea de comandos o un servidor. Cada uno debe tener una función llamada main que defina lo que sucede cuando se ejecuta el ejecutable. Todos los crates que hemos creado hasta ahora han sido crates binarios.

Los crates de biblioteca no tienen una función main, y no se compilan a un ejecutable. En su lugar, definen funcionalidad destinada a ser compartida con múltiples proyectos. Por ejemplo, el crate rand que usamos en el Capítulo 2 proporciona funcionalidad que genera números aleatorios. La mayor parte del tiempo, cuando los Rustaceans dicen “crate”, se refieren a crate de biblioteca, y usan “crate” indistintamente con el concepto general de programación de una “biblioteca”.

El crate root es un archivo fuente que el compilador Rust comienza y forma el módulo raíz de tu crate (explicaremos los módulos en profundidad en la sección “Definir Módulos para Controlar el Alcance y la Privacidad”).

Un paquete es un conjunto de uno o más crates que proporciona un conjunto de funcionalidades. Un paquete contiene un archivo Cargo.toml que describe cómo compilar esos crates. Cargo es en realidad un paquete que contiene el crate binario para la herramienta de línea de comandos que has estado usando para compilar tu código. El paquete Cargo también contiene un crate de biblioteca en el que el crate binario depende. Otros proyectos pueden depender del crate de biblioteca Cargo para usar la misma lógica que la herramienta de línea de comandos Cargo usa.

Un paquete puede venir en dos formas: un paquete binario o un paquete libreria. Un paquete puede contener tantos crates binarios como desees, pero como máximo solo un crate de biblioteca. Un paquete debe contener al menos un crate, ya sea un crate de biblioteca o un crate binario.

Veamos qué sucede cuando creamos un paquete. Primero, ingresamos el comando cargo new:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

Después de ejecutar cargo new my-project, usamos ls para ver lo que crea Cargo. En el directorio del proyecto, hay un archivo Cargo.toml, que nos da un paquete. También hay un directorio src que contiene main.rs. Abre Cargo.toml en tu editor de texto, y observa que no hay mención de src/main.rs. Cargo sigue una convención de que src/main.rs es la raíz del crate de un crate binario con el mismo nombre que el paquete. Del mismo modo, Cargo sabe que si el directorio del paquete contiene src/lib.rs, el paquete contiene un crate de biblioteca con el mismo nombre que el paquete, y src/lib.rs es su raíz del crate. Cargo pasa los archivos raíz del crate a rustc para compilar la biblioteca o el binario.

Aquí, tenemos un paquete que solo contiene src/main.rs, lo que significa que solo contiene un crate binario llamado my-project. Si un paquete contiene src/main.rs y src/lib.rs, tiene dos crates: un binario y una biblioteca, ambos con el mismo nombre que el paquete. Un paquete puede tener múltiples crates binarios colocando archivos en el directorio src/bin: cada archivo será un crate binario separado.

Definiendo módulos para controlar el alcance y la privacidad

En esta sección, hablaremos sobre módulos y otras partes del sistema de módulos, es decir, rutas que permiten nombrar elementos; la palabra clave use que trae una ruta dentro del ámbito; y la palabra clave pub para hacer elementos públicos. También discutiremos la palabra clave as, los paquetes externos y el operador glob.

Primero, vamos a empezar con una lista de reglas para tener a mano cuando estés organizando tu código en el futuro. Luego explicaremos cada una de las reglas en detalle.

Hoja de referencia de módulos

Antes nosotros debemos obtener los detalles de los módulos y las rutas, aquí te proporcionamos una referencia rápida sobre cómo funcionan los módulos, las rutas, la palabra clave use y la palabra clave pub en el compilador, y cómo la mayoría de los desarrolladores organizan su código. Vamos a ir tratando ejemplos de cada una de estas reglas a lo largo de este capítulo, pero esta es una buena referencia para tener a mano cuando necesites recordar cómo funcionan los módulos.

• Empezamos desde la raíz del crate: Cuando se compila un crate, el compilador primero busca el código en el archivo raíz del crate (usualmente src/lib.rs para un crate de librería o src/main.rs para un crate binario) para compilar.
• Declarando módulos: En el archivo raíz del crate, puedes declarar nuevos módulos; digamos, que declaras un módulo “garden” con mod garden;. El compilador buscará el código del módulo en estos lugares:
  • Inline, dentro de llaves que reemplazan el punto y coma que sigue a mod garden
  • En el archivo src/garden.rs
  • En el archivo src/garden/mod.rs
• Declarando submódulos: En cualquier archivo que no sea la raíz del crate, puedes declarar submódulos. Por ejemplo, podrías declarar mod vegetables; en src/garden.rs. El compilador buscará el código del submódulo dentro del directorio que se llama igual que el módulo padre en estos lugares:
  • En línea, directamente después de mod vegetables, dentro de llaves que reemplazan el punto y coma que sigue a mod garden
  • En el archivo src/garden/vegetables.rs
  • En el archivo src/garden/vegetables/mod.rs
• Rutas de acceso a código en módulos: Una vez que un módulo es parte de tu crate, puedes referirte al código de ese módulo desde cualquier otro lugar del mismo crate, siempre y cuando las reglas de privacidad lo permitan, usando la ruta al código. Por ejemplo, un tipo Asparagus en el módulo de vegetales del garden se encontraría en crate::garden::vegetables::Asparagus.
• Privado vs. público: El código dentro de un módulo es privado por defecto desde los módulos padres. Para hacer un módulo público, decláralo con pub mod en vez de mod. Para hacer públicos los elementos dentro de un módulo público, usa pub antes de sus declaraciones.
• La palabra clave use: Dentro de un alcance, la palabra clave use crea atajos a elementos para reducir la repetición de rutas largas. En cualquier alcance que pueda referirse a crate::garden::vegetables::Asparagus, puedes crear un atajo con use crate::garden::vegetables::Asparagus; y a partir de entonces solo necesitarás escribir Asparagus para hacer uso de ese tipo en el alcance.

Aquí, crearemos un crate binario llamado backyard que ilustra estas reglas. El directorio del crate, también llamado backyard, contiene estos archivos y directorios:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

El crate raíz es src/main.rs, y contiene:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

La línea mod garden; le dice al compilador que incluya el código que encuentra en src/garden.rs, que es:

pub mod vegetables;

Aquí, pub mod vegetables; significa que el código en src/garden/vegetables.rs también se incluye. Ese código es:

#[derive(Debug)]
pub struct Asparagus {}

¡Ahora entremos en los detalles de estas reglas y demostrémoslas en acción!

Agrupando código relacionado en módulos

Los módulos nos permiten organizar el código dentro de un crate para facilitar su lectura y reutilización. También nos permiten controlar la privacidad de los elementos, ya que el código dentro de un módulo es privado por defecto. Los elementos privados son detalles de la implementación interna que no están disponibles para su uso externo. Podemos elegir hacer públicos los módulos y los elementos que contienen para exponerlos y permitir que el código externo los use y dependa de ellos.

Como un ejemplo, vamos a escribir una librería que provee la funcionalidad de un restaurante. Vamos a definir las firmas de las funciones, pero dejaremos sus cuerpos vacíos para concentrarnos en la organización del código, en vez de la implementación de un restaurante.

En la industria de restaurantes, algunas partes de un restaurante se llaman front of house y otras back of house. El front of house es donde están los clientes; esto incluye donde los anfitriones se sientan a los clientes, los camareros toman los pedidos y el pago, y los bartenders preparan las bebidas. El back of house es donde los chefs y los cocineros trabajan en la cocina, los lavaplatos limpian, y los gerentes hacen el trabajo administrativo.

Para estructurar nuestro crate de esta manera, podemos organizar sus funciones dentro de módulos anidados. Crea una nueva librería llamada restaurant ejecutando cargo new restaurant --lib. Luego ingresa el código en el Listado 7-1 para definir algunos módulos y firmas de funciones. Aquí está la sección front of house:

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Definimos un módulo con la palabra clave mod seguida del nombre del módulo (en este caso, front_of_house). El cuerpo del módulo va dentro de llaves. Dentro de los módulos, podemos colocar otros módulos, como en este caso con los módulos hosting y serving. Los módulos también pueden contener definiciones de otros elementos, como structs, enums, constantes, traits, y como en la Lista 7-1—funciones.

Mediante el uso de módulos, podemos agrupar definiciones relacionadas y nombrar por qué están relacionadas. Los programadores que usen este código pueden navegar el código basándose en los grupos en vez de tener que leer todas las definiciones, haciendo más fácil encontrar las definiciones relevantes para ellos. Los programadores que agreguen nueva funcionalidad a este código sabrán dónde colocar el código para mantener el programa organizado.

Anteriormente, mencionamos que src/main.rs y src/lib.rs se llaman raíces de crate. La razón de su nombre es que el contenido de cualquiera de estos dos archivos forma un módulo llamado crate en la raíz de la estructura de módulos del crate, conocida como el árbol de módulos.

El Listado 7-2 muestra el árbol de módulos para la estructura en el listado 7-1

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Este árbol muestra como algunos de los módulos se anidan dentro de otros módulos; por ejemplo, hosting se anida dentro de front_of_house. El árbol también muestra que algunos módulos son hermanos entre sí, lo que significa que están definidos en el mismo módulo; hosting y serving son hermanos definidos dentro de front_of_house. Si el módulo A está contenido dentro del módulo B, decimos que el módulo A es el hijo del módulo B y que el módulo B es el padre del módulo A. Nota que el árbol de módulos completo está enraizado bajo el módulo implícito llamado crate.

El árbol de módulos puede recordarte al árbol de directorios del sistema de archivos en tu computadora; ¡esta es una comparación muy apropiada! Al igual que los directorios en un sistema de archivos, usas módulos para organizar tu código. Y al igual que los archivos en un directorio, necesitamos una forma de encontrar nuestros módulos.

Rutas para referirse a un elemento en el árbol de módulos

Para mostrarle a Rust dónde encontrar un item en el árbol de módulos, usamos una ruta de la misma manera que usamos una ruta cuando navegamos en un sistema de archivos. Para llamar a una función, necesitamos saber su ruta.

Una ruta puede tomar dos formas:

• Una ruta absoluta es la ruta completa que comienza desde la raíz de un crate; para el código de un crate externo, la ruta absoluta comienza con el nombre del crate, y para el código del crate actual, comienza con el crate literal.

• Una ruta relativa comienza desde el módulo actual y utiliza self, super, o un identificador del módulo actual.

Tanto las rutas absolutas como las relativas están seguidas por uno o más identificadores separados por dos puntos dobles (::).

Volviendo al listado 7-1, digamos que queremos llamar a la función add_to_waitlist desde la función eat_at_restaurant definida en el crate root. Este es el mismo que preguntar: ¿cuál es la ruta de la función add_to_waitlist? El listado 7-3 contiene el listado 7-1 con algunos de los módulos y funciones removidas.

Mostraremos dos formas de llamar a la función add_to_waitlist desde una nueva función, eat_at_restaurant, definida en el crate de la raíz. Estas rutas son correctas, pero hay otro problema que impide que este ejemplo compile tal cual. Explicaremos por qué en un momento.

La función eat_at_restaurant es parte de la API pública del crate de nuestra librería, así que la marcamos con la palabra clave pub. En la sección “Exponiendo Rutas con la palabra clave pub”, iremos en más detalle sobre pub.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

La primera vez que llamamos a la función add_to_waitlist en eat_at_restaurant, usamos una ruta absoluta. La función add_to_waitlist está definida en el mismo crate que eat_at_restaurant, lo que significa que podemos usar la palabra clave crate para comenzar una ruta absoluta. Luego incluimos cada uno de los módulos sucesivos hasta que llegamos a add_to_waitlist. Puedes imaginar un sistema de archivos con la misma estructura: especificaríamos la ruta /front_of_house/hosting/add_to_waitlist para ejecutar el programa add_to_waitlist; usar el nombre crate para comenzar desde la raíz del crate es como usar / para comenzar desde la raíz del sistema de archivos en tu shell.

La segunda vez que llamamos a add_to_waitlist en eat_at_restaurant, usamos la ruta relativa. La ruta comienza con front_of_house, el nombre del módulo definido al mismo nivel del árbol de módulos que eat_at_restaurant. Aquí el equivalente en el sistema de archivos sería usar la ruta front_of_house/hosting/add_to_waitlist. Comenzar con el nombre del módulo significa que la ruta es relativa.

Elegir si usar una ruta relativa o absoluta es una decisión que tomarás basado en tu proyecto, y depende de si es más probable que muevas la definición de un item de código separadamente o junto con el código que usa el item. Por ejemplo, si movemos el módulo front_of_house y la función eat_at_restaurant a un módulo llamado customer_experience, necesitaríamos actualizar la ruta absoluta a add_to_waitlist, pero la ruta relativa seguiría siendo válida. Sin embargo, si movemos la función eat_at_restaurant separadamente a un módulo llamado dining, la ruta absoluta a la llamada de add_to_waitlist seguiría siendo la misma, pero la ruta relativa necesitaría ser actualizada. Nuestra preferencia en general es especificar rutas absolutas porque es más probable que queramos mover definiciones de código y llamadas de items independientemente.

¡Intentemos compilar el listado 7-3 y averigüemos por qué aún no compila! Los errores que obtenemos se muestran en el listado 7-4.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
2  |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

El mensaje de error dice que el módulo hosting es privado. En otras palabras, tenemos las rutas correctas para el módulo hosting y la función add_to_waitlist, pero Rust no nos deja usarlos porque no tiene acceso a las secciones privadas. En Rust, todos los items (funciones, métodos, structs, enums, módulos, y constantes) son privados a los módulos padres por defecto. Si quieres hacer un item como una función o struct privado, lo pones en un módulo.

Los elementos en un módulo privado no pueden ser accedidos por una ruta externa absoluta, porque el módulo padre no puede ver dentro de los módulos privados de sus hijos. El módulo padre puede ver el contenido de sus módulos hijos porque los módulos hijos están dentro del módulo padre. Para continuar con nuestra metáfora, piensa en las reglas de privacidad como la oficina de atrás de un restaurante: lo que pasa ahí es privado para los clientes del restaurante, pero los gerentes de la oficina pueden ver y hacer todo en el restaurante que operan.

Rust elige tener el sistema de módulos funcionando de esta forma para que ocultar detalles de implementación internos sea lo predeterminado. De esta forma, sabes qué partes del código interno puedes cambiar sin romper el código externo. Sin embargo, Rust te da la opción de exponer partes internas del código de los módulos hijos a los módulos ancestros externos usando la palabra clave pub para hacer un item público.

Exponiendo rutas con la palabra clave pub

Volviendo al error en el listado 7-4 que nos dijo que el módulo hosting es privado, queremos que la función eat_at_restaurant en el módulo padre tenga acceso a la función add_to_waitlist en el módulo hijo, así que marcamos el módulo hosting con la palabra clave pub, como se muestra en el listado 7-5.

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

Desafortunadamente, el código en el listado 7-5 aún resulta en errores de compilador, como se muestra en el listado 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
 --> src/lib.rs:9:37
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                                     ^^^^^^^^^^^^^^^ private function
  |
note: the function `add_to_waitlist` is defined here
 --> src/lib.rs:3:9
  |
3 |         fn add_to_waitlist() {}
  |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:12:30
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
3  |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

¿Qué pasó? Agregar la palabra clave pub al frente del módulo hosting hace que el módulo sea público. Con este cambio, si podemos acceder a front_of_house, podemos acceder a hosting. Pero el contenido de hosting sigue siendo privado; hacer el módulo público no hace que su contenido sea público. La palabra clave pub en un módulo solo permite que el código en sus módulos ancestros se refiera a él, no acceder a su código interno. Debido a que los módulos son contenedores, no hay mucho que podamos hacer solo haciendo que el módulo sea público; necesitamos ir más allá y elegir hacer que uno o más de los items dentro del módulo sean públicos también.

El error en el listado 7-6 dicen que la función add_to_waitlist es privada. Las reglas de privacidad se aplican a structs, enums, funciones, y métodos, así como a módulos.

Para hacer que la función add_to_waitlist sea pública, necesitamos agregar la palabra clave pub antes de su definición, como se muestra en el listado 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

¡Ahora el código compilará! Para ver por qué agregar la palabra clave pub nos permite usar estas rutas en eat_at_restaurant con respecto a las reglas de privacidad, veamos las rutas absolutas y relativas.

En la ruta absoluta, comenzamos con crate, la raíz del árbol de módulos de nuestro crate. El módulo front_of_house está definido en la raíz del crate. Si bien front_of_house no es público, porque la función eat_at_restaurant está definida en el mismo módulo que front_of_house (es decir, eat_at_restaurant y front_of_house son hermanos), podemos referirnos a front_of_house desde eat_at_restaurant. A continuación está el módulo hosting marcado con pub. Podemos acceder al módulo padre de hosting, por lo que podemos acceder a hosting. ¡Finalmente, la función add_to_waitlist está marcada con pub y podemos acceder a su módulo padre, por lo que está llamada a función funciona!

En la ruta relativa, la lógica es la misma que la ruta absoluta, excepto por el primer paso: en lugar de comenzar desde la raíz del crate, la ruta comienza desde front_of_house. El módulo front_of_house está definido dentro del mismo módulo que eat_at_restaurant, por lo que la ruta relativa que comienza desde el módulo en el que se define eat_at_restaurant funciona. Luego, porque hosting y add_to_waitlist están marcados con pub, el resto de la ruta funciona, ¡y está llamada a función es válida!

Si planeas compartir tu biblioteca crate para que otros proyectos puedan usar tu código, tu API pública es tu contrato con los usuarios de tu crate que determina cómo pueden interactuar con tu código. Hay muchas consideraciones sobre cómo administrar los cambios en tu API pública para que sea más fácil que la gente dependa de tu crate. Estas consideraciones están fuera del alcance de este libro; si estás interesado en este tema, consulta The Rust API Guidelines.

Buenas prácticas para paquetes con un binario y una biblioteca

Mencionamos que un paquete puede contener tanto un binario src/main.rs como una biblioteca src/lib.rs, y ambos tendrán el nombre del paquete de forma predeterminada. Típicamente, los paquetes con este patrón de contener tanto una biblioteca como un binario tendrán solo el código suficiente en el binario para iniciar un ejecutable que llame al código con la biblioteca. Esto permite que otros proyectos se beneficien de que la mayor funcionalidad que proporciona el paquete, porque el código de la biblioteca se puede compartir.

El árbol de módulos debería ser definido en src/lib.rs. Luego, cualquier item público puede ser usado en el binario comenzando las rutas con el nombre del paquete. El binario se convierte en un usuario de la biblioteca de la misma forma que un crate completamente externo usaría la biblioteca: solo puede usar la API pública. Esto te ayuda a diseñar una buena API; no solo eres el autor, ¡también eres un cliente!

En el Capítulo 12, demostraremos esta práctica organizativa con un programa de línea de comandos que contendrá tanto un paquete binario como una biblioteca.

Comenzando rutas relativas con super

Podemos construir rutas relativas que comiencen en el módulo padre, en lugar de en el módulo actual o en la raíz del crate, usando super al comienzo de la ruta. Esto es como comenzar una ruta del sistema de archivos con la sintaxis ... Usar super nos permite hacer referencia a un item que sabemos que está en el módulo padre, lo que puede facilitar la reorganización del árbol de módulos cuando el módulo está estrechamente relacionado con el padre, pero el padre podría moverse a otro lugar en el árbol de módulos algún día.

Considere el código en el listado 7-8 que modela la situación en la que un chef arregla un pedido incorrecto y lo trae personalmente al cliente. La función fix_incorrect_order definida en el módulo back_of_house llama a la función deliver_order definida en el módulo padre especificando la ruta a deliver_order, comenzando con super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

La función fix_incorrect_order está en el módulo back_of_house, por lo que podemos usar super para ir al módulo padre de back_of_house, que en este caso es crate, la raíz. Desde allí, buscamos deliver_order y lo encontramos. ¡Éxito! Pensamos que el módulo back_of_house y la función deliver_order probablemente permanecerán en la misma relación entre sí y se moverán juntos si decidimos reorganizar el árbol de módulos del crate. Por lo tanto, usamos super para tener menos lugares para actualizar el código en el futuro si este código se mueve a un módulo diferente.

Haciendo públicos los structs y enums

También podemos usar pub para designar structs y enums como públicos, pero hay algunos detalles adicionales para el uso de pub con structs y enums. Si usamos pub antes de una definición de struct, hacemos que el struct sea público, pero los campos del struct seguirán siendo privados. Podemos hacer que cada campo sea público o no caso por caso. En el listado 7-9, hemos definido un struct back_of_house::Breakfast público con un campo toast público pero un campo seasonal_fruit privado. Esto modela el caso en un restaurante donde el cliente puede elegir el tipo de pan que viene con una comida, pero el chef decide qué fruta acompaña la comida según lo que está en temporada y en stock. La fruta disponible cambia rápidamente, por lo que los clientes no pueden elegir la fruta o incluso ver qué fruta obtendrán.

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal
    // meal.seasonal_fruit = String::from("blueberries");
}

Debido a que el campo toast es público, podemos cambiar el valor de toast en una instancia de Breakfast en la función eat_at_restaurant en el listado 7-10. Ten en cuenta que no podemos usar el campo seasonal_fruit en eat_at_restaurant, porque seasonal_fruit es privado. ¡Intenta descomentar la línea que modifica el valor del campo seasonal_fruit para ver qué error obtiene!

Además, ten en cuenta que debido a que back_of_house::Breakfast tiene un campo privado, el struct debe proporcionar una función asociada pública que construya una instancia de Breakfast (lo hemos llamado summer aquí). Si Breakfast no tuviera tal función, no podríamos crear una instancia de Breakfast en eat_at_restaurant porque no podríamos establecer el valor del campo privado seasonal_fruit en eat_at_restaurant.

Por el contrario, si hacemos un enum público, todos sus variantes son públicas. Solo necesitamos el pub antes de la palabra clave enum, como se muestra en el listado 7-10.

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

Debido a que hicimos el enum Appetizer público, podemos usar las variantes Appetizer::Soup y Appetizer::Salad en eat_at_restaurant.

Los Enums no son muy útiles a menos que sus variantes sean públicas; sería molesto tener que anotar todas las variantes de enum con pub en todos los casos, por lo que el valor predeterminado para las variantes de enum es ser público. Los structs a menudo son útiles sin que sus campos sean públicos, por lo que los campos de struct siguen la regla general de que todo es privado por defecto a menos que se anote con pub.

Hay una situación más relacionada con pub que no hemos cubierto, y es nuestra última característica del sistema de módulos: la palabra clave use. Cubriremos use por sí solo primero, y luego mostraremos cómo combinar pub y use.

Incluyendo rutas al ámbito con la palabra clave use

Tener que escribir las rutas para llamar a las funciones puede sentirse inconveniente y repetitivo. En el Listado 7-7, si elegimos la ruta absoluta o relativa para la función add_to_waitlist, cada vez que queríamos llamar a add_to_waitlist teníamos que especificar front_of_house y hosting también. Afortunadamente, hay una manera de simplificar este proceso: podemos crear un atajo a una ruta con la palabra clave use una vez, y luego usar el nombre más corto en todas partes en el ámbito.

En el listado 7-11, traemos el módulo crate::front_of_house::hosting al ámbito de la función eat_at_restaurant para que solo tengamos que especificar hosting::add_to_waitlist para llamar a la función add_to_waitlist en eat_at_restaurant.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Agregar use y una ruta en un ámbito es similar a crear un enlace simbólico en el sistema de archivos. Al agregar use crate::front_of_house::hosting en la raíz del crate, hace que hosting sea ahora un nombre válido en ese ámbito, como si el módulo hosting hubiera sido definido en la raíz del crate. Las rutas traídas al ámbito con use también verifican la privacidad, como cualquier otra ruta.

Ten en cuenta que use solo crea el atajo para el ámbito particular en el que ocurre él use. El Listado 7-12 mueve la función eat_at_restaurant a un nuevo módulo hijo llamado customer, que es entonces un ámbito diferente al de la sentencia use, por lo que el cuerpo de la función no compilará.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

El error del compilador muestra que el acceso directo ya no se aplica dentro del módulo del customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of undeclared crate or module `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of undeclared crate or module `hosting`
   |
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

Observe que también hay una advertencia de que él use ya no se utiliza en su ámbito. Para solucionar este problema, mueva también él use dentro del módulo customer, o haga referencia al acceso directo en el módulo padre con super::hosting dentro del módulo hijo customer.

Creando rutas de use idiomaticas

En el Listado 7-11, podrías haberte preguntado por qué especificamos use crate::front_of_house::hosting y luego llamamos a hosting::add_to_waitlist en eat_at_restaurant, en lugar de especificar toda la ruta hasta la función add_to_waitlist para lograr el mismo resultado, como en el Listado 7-13.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

Aunque el Listado 7-11 y 7-13 logran la misma tarea, el Listado 7-11 es la forma idiomática de traer una función al ámbito con use. Traer el módulo padre de la función al ámbito con use significa que tenemos que especificar el módulo padre cuando llamamos a la función. Especificar el módulo padre cuando llamamos a la función hace que quede claro que la función no está definida localmente, al tiempo que minimiza la repetición de la ruta completa. El código en el Listado 7-13 no es claro en cuanto a dónde se define add_to_waitlist.

Por otro lado, cuando traemos structs, enums y otros items con use, es idiomático especificar la ruta completa. El Listado 7-14 muestra la forma idiomática de traer la struct HashMap de la biblioteca estándar al ámbito de un crate binario.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

No hay una razón fuerte detrás de este idioma: es solo la convención que ha surgido, y la gente se ha acostumbrado a leer y escribir código Rust de esta manera.

La excepción a este idioma es si estamos trayendo dos elementos con el mismo nombre al ámbito con declaraciones use, porque Rust no lo permite. El Listado 7-15 muestra cómo traer dos tipos Result al ámbito que tienen el mismo nombre pero módulos padres diferentes, y cómo referirse a ellos.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

Como puedes ver, usar los módulos padres distingue los dos tipos Result. Sí, en cambio, especificamos use std::fmt::Result y use std::io::Result, tendríamos dos tipos Result en el mismo ámbito, y Rust no sabría a cuál nos referimos cuando usamos Result.

Proporcionando nuevos nombres con el Keyword as

Hay otra solución a este problema de traer dos elementos con el mismo nombre al ámbito con use: después de la ruta, podemos especificar as y un nuevo nombre local, o alias, para el tipo. El Listado 7-16 muestra otra forma de escribir el código en el Listado 7-15 renombrando uno de los dos tipos Result usando as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

En la segunda declaración use, elegimos el nuevo nombre IoResult para el tipo std::io::Result, que no entrará en conflicto con el Result de std::fmt que también hemos traído al ámbito. El Listado 7-15 y 7-16 se consideran idiomáticos, ¡así que la elección depende de ti!

Re-exportando nombres con pub use

Cuando traemos un nombre al ámbito con la keyword use, el nombre está disponible en ese ámbito de forma privada. Si queremos que el nombre esté disponible para que el código que llama a nuestro código lo use, podemos combinar pub y use. Esta técnica se llama re-exporting porque estamos trayendo un elemento al ámbito, pero también haciendo que ese elemento esté disponible para que otros lo traigan a su ámbito.

El listado 7-17 muestra el código del listado 7-11 con use en el módulo front_of_house cambiado a pub use.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Antes de este cambio, el código externo tendría que llamar a la función add_to_waitlist usando la ruta restaurant::front_of_house::hosting::add_to_waitlist(), el cual también debería tener requerido el modulo front_of_house para ser marcado como pub. Ahora que este pub use ha reexportado el módulo hosting desde el módulo raíz, el código externo puede usar la ruta restaurant::hosting::add_to_waitlist() en su lugar.

Re-exportar es útil cuando la estructura interna de tu código es diferente de cómo los programadores que llaman a tu código pensarían sobre el dominio. Por ejemplo, en esta metáfora de un restaurante, la gente que dirige el restaurante piensa en “front of house” y “back of house”. Pero los clientes que visitan un restaurante probablemente no pensarán en las partes del restaurante en esos términos. Con pub use, podemos escribir nuestro código con una estructura pero exponer una estructura diferente. Hacerlo hace que nuestra biblioteca esté bien organizada para los programadores que trabajan en la biblioteca y los programadores que llaman a la biblioteca. Veremos otro ejemplo de pub use y cómo afecta la documentación de tu crate en la sección “Exportando una API pública conveniente con pub use” del Capítulo 14.

Usando paquetes externos

En el Capítulo 2, programamos un proyecto de juego de adivinanzas que usaba un paquete externo llamado rand para obtener números aleatorios. Para usar rand en nuestro proyecto, agregamos esta línea a Cargo.toml:

rand = "0.8.5"

Añadir rand como dependencia en Cargo.toml le dice a Cargo que descargue el paquete rand y cualquier dependencia de crates.io y haga que rand esté disponible para nuestro proyecto.

Luego, para llevar las definiciones de rand al ámbito de nuestro paquete, agregamos una línea use que comienza con el nombre del paquete, rand, y enumera los items que queremos traer al ámbito. Recuerda que en la sección “Generando un número aleatorio” del Capítulo 2, traíamos el trait Rng al ámbito y llamábamos a la función rand::thread_rng:

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Los miembros de la comunidad de Rust han puesto muchos paquetes disponibles en crates.io, y traer cualquiera de ellos a tu paquete involucra estos mismos pasos: listarlos en el archivo Cargo.toml de tu paquete y usar use para traer items de sus crates al ámbito.

Ten en cuenta que la biblioteca estándar std también es una crate externa a nuestro paquete. Debido a que la biblioteca estándar se envía con el lenguaje Rust, no necesitamos cambiar Cargo.toml para incluir std. Pero sí necesitamos referirnos a él con use para traer items de allí al ámbito de nuestro paquete. Por ejemplo, con HashMap usaríamos esta línea:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

Esta es una ruta absoluta que comienza con std, el nombre del crate de la biblioteca estándar. También podríamos escribir este use como:

Usando rutas anidadas para limpiar listas use grandes

Si estamos usando varios elementos definidos en el mismo crate o el mismo módulo, enumerar cada elemento en su propia línea puede ocupar mucho espacio vertical en nuestros archivos. Por ejemplo, estas dos declaraciones use que teníamos en el juego de adivinanzas en el Listado 2-4 traen items de std al ámbito:

use rand::Rng;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

En su lugar, podemos utilizar rutas anidadas para incluir los mismos elementos en una sola línea. Hacemos esto especificando la parte común de la ruta, seguida de dos puntos y luego entre llaves los elementos, como se muestra en el Listado 7-18.

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

En programas más grandes, traer muchos items al ámbito desde el mismo crate o módulo usando rutas anidadas puede reducir la cantidad de declaraciones use necesarias en gran medida.

Podemos usar una ruta anidada en cualquier nivel de una ruta, lo que es útil cuando combinamos dos sentencias use que comparten una sub-ruta. Por ejemplo, el Listado 7-19 muestra dos sentencias use: una que trae std::io al ámbito y otra que trae std::io::Write al ámbito.

use std::io;
use std::io::Write;

La parte común de estas dos rutas es std::io, así que podemos usar una ruta anidada para traer ambos al ámbito en una línea, como se muestra en el Listado 7-20.

use std::io::{self, Write};

Esta línea trae std::io y std::io::Write al ámbito.

El Operador Asterisco (Glob)

Si queremos incluir al ámbito todos los elementos públicos definidos en una ruta, podemos especificar esa ruta seguido del operador glob *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

Esta sentencia use trae todos los elementos públicos definidos en std::collections al ámbito actual. Tenga cuidado al utilizar el operador glob. El operador glob puede hacer más difícil saber qué elementos están en el ámbito y dónde se definió un elemento que este siendo utilizado en su programa.

El operador glob se utiliza a menudo cuando se realizan pruebas para llevar todo lo que se está probando al módulo de pruebas; hablaremos de ello en la sección "Cómo escribir pruebas" del capítulo 11. El operador glob también se utiliza a veces como parte del patrón prelude: consulte la documentación de la biblioteca estándar para obtener más información sobre ese patrón.

Separando módulos en diferentes archivos

Hasta ahora, todos los ejemplos en este capítulo definían varios módulos en un archivo. Cuando los módulos se vuelven grandes, es posible que desees mover sus definiciones a un archivo separado para que el código sea más fácil de navegar.

Por ejemplo, comencemos desde el código en el listado 7-17 que tenía múltiples módulos de restaurante. Extraeremos los módulos en archivos en lugar de tener todos los módulos definidos en el archivo raíz del crate. En este caso, el archivo raíz del crate es src/lib.rs, pero este procedimiento también funciona con crates binarios cuyo archivo raíz del crate es src/main.rs.

Primero, extraeremos el módulo front_of_house a su propio archivo. Elimine el código dentro de las llaves para el módulo front_of_house, dejando solo la declaración mod front_of_house;, de modo que src/lib.rs contenga el código que se muestra en el listado 7-21. Ten en cuenta que esto no compilará hasta que creemos el archivo src/front_of_house.rs en el listado 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

Luego, coloca el código que estaba entre las llaves en un nuevo archivo llamado src/front_of_house.rs, como se muestra en el Listado 7-22. El compilador sabe que debe buscar en este archivo porque se encontró con la declaración del módulo en la raíz del crate con el nombre front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

Ten en cuenta que solo necesitas cargar un archivo usando una declaración mod una vez en tu árbol de módulos. Una vez que el compilador sabe que el archivo es parte del proyecto (y sabe en qué parte del árbol de módulos reside el código debido a dónde has puesto la declaración mod), otros archivos en tu proyecto deben hacer referencia al código del archivo cargado usando una ruta que indique donde se declaró, como se cubre en la sección “Rutas para referirse a un elemento en el árbol de módulos”. En otras palabras, mod no es una operación de “incluir” que puede haber visto en otros lenguajes de programación.

Luego, extraeremos el módulo hosting a su propio archivo. El proceso es un poco diferente porque hosting es un módulo secundario de front_of_house, no del módulo raíz. Colocaremos el archivo para hosting en un nuevo directorio que se llamará por sus antepasados en el árbol de módulos, en este caso src/front_of_house.

Para comenzar a mover hosting, cambiamos src/front_of_house.rs para contener solo la declaración del módulo hosting:

pub mod hosting;

Luego creamos un directorio src/front_of_house y un archivo hosting.rs para contener las definiciones realizadas en el módulo hosting:

pub fn add_to_waitlist() {}

Sí, en cambio, colocamos hosting.rs en el directorio src, el compilador esperaría que el código de hosting.rs estuviera en un módulo hosting declarado en la raíz del crate, y no declarado como un hijo del módulo front_of_house. Las reglas del compilador sobre qué archivos comprobar para cada código de módulo hacen que los directorios y archivos se ajusten más al árbol de módulos.

Rutas alternativas de archivos

Hasta ahora hemos cubierto las rutas de archivos más idiomáticas que utiliza el compilador de Rust, pero Rust también admite un estilo más antiguo de ruta de archivo. Para un módulo llamado front_of_house declarado en la raíz del crate, el compilador buscará el código del módulo en:

• src/front_of_house.rs (lo que cubrimos)
• src/front_of_house/mod.rs (estilo antiguo, ruta aún soportada)

Para un módulo llamado hosting que es un submódulo de front_of_house, el compilador buscará el código del módulo en:

• src/front_of_house/hosting.rs (lo que cubrimos)
• src/front_of_house/hosting/mod.rs (estilo antiguo, ruta aún soportada)

Si usas ambos estilos para el mismo módulo, obtendrás un error del compilador. Usar una mezcla de ambos estilos para diferentes módulos en el mismo proyecto está permitido, pero podría ser confuso para las personas que navegan por tu proyecto.

La principal desventaja del estilo que usa archivos llamados mod.rs es que tu proyecto puede terminar con muchos archivos llamados mod.rs, lo que puede ser confuso cuando los tienes abiertos en tu editor al mismo tiempo.

Hemos movido el código de cada módulo a un archivo separado, y el árbol de módulos permanece igual. Las llamadas a las funciones de eat_at_restaurant funcionarán sin ninguna modificación, incluso si las definiciones viven en archivos diferentes. Esta técnica le permite mover módulos a nuevos archivos a medida que crecen en tamaño.

Ten en cuenta que la declaración pub use crate::front_of_house::hosting en src/lib.rs tampoco ha cambiado, ni use tiene ningún impacto en qué archivos se compilan como parte del crate. La palabra clave mod declara módulos, y Rust busca en un archivo con el mismo nombre que el módulo para el código que va en ese módulo.

Resumen

Rust te permite dividir un paquete en múltiples crates y un crate en módulos para que puedas referirte a elementos definidos en un módulo desde otro módulo. Puedes hacer esto especificando rutas absolutas o relativas. Estas rutas se pueden traer al ámbito con una declaración use para que puedas usar una ruta más corta para múltiples usos del elemento en ese ámbito. El código de los módulos es privado por defecto, pero puedes hacer que las definiciones sean públicas agregando la palabra clave pub.

En el siguiente capítulo, veremos algunas estructuras de datos de colección en la biblioteca estándar que puedes usar en tu código bien organizado.

Colecciones comunes

La biblioteca estándar de Rust incluye una serie de estructuras de datos muy útiles llamadas colecciones. La mayoría de los otros tipos de datos representan un valor específico, pero las colecciones pueden contener varios valores. A diferencia de los tipos de datos built-in array y tupla, los datos a los que apuntan estas colecciones se almacenan en el heap, lo que significa que la cantidad de datos no necesita conocerse en el momento de la compilación y puede crecer o disminuir a medida que se ejecuta el programa. Cada tipo de colección tiene diferentes capacidades y costos, y elegir uno apropiado para su situación actual es una habilidad que desarrollará con el tiempo. En este capítulo, discutiremos tres colecciones que se usan muy a menudo en los programas Rust:

• Un vector le permite almacenar un número variable de valores uno al lado del otro.
• Un string es una colección de caracteres. Hemos mencionado el tipo String anteriormente, pero en este capítulo hablaremos de él en profundidad.
• Un hash map le permite asociar un valor con una clave especifica. Es una implementación particular de la estructura de datos más general llamada map.

Para aprender sobre los otros tipos de colecciones proporcionados por la biblioteca estándar, consulte la documentación.

Discutiremos cómo crear y actualizar vectores, strings y hash maps, así como lo que hace que cada uno sea especial.

Almacenando listas de valores con vectores

El primer tipo de colección que veremos es Vec<T>, también conocido como un vector. Los vectores te permiten almacenar más de un valor en una sola estructura de datos que pone todos los valores uno al lado del otro en la memoria. Los vectores solo pueden almacenar valores del mismo tipo. Son útiles cuando tienes una lista de elementos, como las líneas de texto en un archivo o los precios de los artículos en un carrito de compras.

Creando un nuevo vector

Para crear un nuevo vector vacío, llamamos a la función Vec::new, como se muestra en el listado 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

Ten en cuenta que agregamos una anotación de tipo aquí. Como no estamos insertando ningún valor en este vector, Rust no sabe qué tipo de elementos queremos almacenar. Este es un punto importante. Los vectores se implementan usando genéricos; cubriremos cómo usar genéricos con tus propios tipos en el Capítulo 10. Por ahora, sepa que el tipo Vec<T> proporcionado por la biblioteca estándar puede contener cualquier tipo. Cuando creamos un vector para contener un tipo específico, podemos especificar el tipo dentro de corchetes angulares. En el listado 8-1, le hemos dicho a Rust que el Vec<T> en v contendrá elementos del tipo i32.

A menudo, crearás un Vec<T> con valores iniciales y Rust inferirá el tipo de valor que deseas almacenar, por lo que rara vez necesitarás hacer esta anotación de tipo. Rust proporciona convenientemente la macro vec!, que creará un nuevo vector que contenga los valores que le des. El listado 8-2 crea un nuevo Vec<i32> que contiene los valores 1, 2 y 3. El tipo entero es i32 porque ese es el tipo entero predeterminado, como discutimos en la sección "Tipos de datos" del Capítulo 3.

fn main() {
    let v = vec![1, 2, 3];
}

Debido a que hemos dado valores iniciales i32, Rust puede inferir que el tipo de v es Vec<i32>, y la anotación de tipo no es necesaria. A continuación, veremos cómo modificar un vector.

Actualizando un vector

Para crear un vector y luego agregar elementos a él, podemos usar el método push, como se muestra en el listado 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

Como con cualquier variable, si queremos poder cambiar su valor, necesitamos hacerlo mutable usando la palabra clave mut, como se discutió en el Capítulo 3. Los números que colocamos dentro son todos del tipo i32, y Rust infiere esto de los datos, por lo que no necesitamos la anotación Vec<i32>.

Leyendo elementos de vectores

Hay dos formas de hacer referencia a un valor almacenado en un vector: a través de la indexación o usando el método get. En los siguientes ejemplos, hemos anotado los tipos de los valores que se devuelven de estas funciones para obtener una mayor claridad.

En el listado 8-4 se muestran ambos métodos de acceso a un valor en un vector, con sintaxis de indexación y el método get.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

Ten en cuenta algunos detalles aquí. Usamos el valor de índice 2 para obtener el tercer elemento porque los vectores se indexan por número, comenzando en cero. Usar & y [] nos da una referencia al elemento en el índice. Cuando usamos el método get con el índice pasado como argumento, obtenemos un Option<&T> que podemos usar con match.

La razón por la que Rust proporciona estas dos formas de hacer referencia a un elemento es para que puedas elegir cómo se comporta el programa cuando intentas usar un valor de índice fuera del rango de elementos existentes. Como ejemplo, veamos qué sucede cuando tenemos un vector de cinco elementos y luego intentamos acceder a un elemento en el índice 100 con cada técnica, como se muestra en el listado 8-5.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

Cuando ejecutamos este código, el primer método [] causará que el programa falle porque intenta acceder a un elemento que no existe. Este método es mejor usarlo cuando quieres que tu programa se bloquee si hay un intento de acceder a un elemento más allá del final del vector.

Cuando el método get se pasa un índice que está fuera del rango del vector, simplemente devuelve None sin entrar en pánico. Tendrías que usar este método si acceder a un elemento más allá del rango del vector puede suceder con frecuencia en circunstancias normales. Tu código tendrá entonces la lógica necesaria para gestionar la presencia de Some(&element) o None, tal y como se explica en el capítulo 6. Por ejemplo, el índice podría provenir de una persona que ingresa un número. Si ingresan accidentalmente un número que es demasiado grande y el programa obtiene un valor None, podrías decirle al usuario cuántos elementos hay en el vector actual y darle otra oportunidad de ingresar un valor válido. Eso sería más amigable para el usuario que bloquear el programa debido a un error tipográfico.

Cuando el programa tiene una referencia válida, el borrow checker hace cumplir las reglas de ownership y borrowing (cubiertas en el Capítulo 4) para asegurar que esta referencia y cualquier otra referencia a los contenidos del vector permanezcan válidas. Recuerda la regla que establece que no puedes tener referencias mutables e inmutables en el mismo ámbito. Esa regla se aplica en el listado 8-6, donde tenemos una referencia inmutable al primer elemento en un vector e intentamos agregar un elemento al final. Este programa no funcionará si también intentamos referirnos a ese elemento más adelante en la función.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

Al compilar este código se producirá este error:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                     ------- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` (bin "collections") due to 1 previous error

El código en el listado 8-6 podría parecer que debería funcionar: ¿por qué una referencia al primer elemento se preocuparía por los cambios al final del vector? Este error se debe a la forma en que funcionan los vectores: porque los vectores colocan los valores uno al lado del otro en la memoria, agregar un nuevo elemento al final del vector puede requerir asignar nueva memoria y copiar los elementos antiguos al nuevo espacio, si no hay suficiente espacio para poner todos los elementos uno al lado del otro donde se almacena el vector actualmente. En ese caso, la referencia al primer elemento apuntaría a la memoria desasignada. Las reglas de borrowing evitan que los programas terminen en esa situación.

Nota: Para más información sobre los detalles de implementación del tipo Vec<T>, véase "The Rustonomicon".

Iterando sobre los valores en un vector

Para acceder a cada elemento en un vector a su vez, iteramos a través de todos los elementos, en lugar de usar índices para acceder a uno a la vez. El listado 8-7 muestra cómo usar un bucle for para obtener referencias inmutables a cada elemento en un vector de valores i32 e imprimirlos.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

También podemos iterar sobre referencias mutables a cada elemento en un vector mutable, lo que nos permite cambiar los valores en un vector en el lugar. El código en el listado 8-8 agregará 50 a cada elemento en un vector.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

Para cambiar el valor al que se refiere la referencia mutable, tenemos que usar el operador de desreferencia * para llegar al valor en i antes de poder usar el operador +=. Hablaremos más sobre el operador de desreferencia en la sección “Siguiendo el puntero al valor con el operador de desreferencia” del Capítulo 15.

Iterando sobre un vector, ya sea inmutable o mutable, es seguro debido a las reglas del borrow checker. Si intentáramos insertar o eliminar elementos en los cuerpos del ciclo for en el listado 8-7 y el listado 8-8, obtendríamos un error del compilador similar al que obtuvimos con el código en el listado 8-6. La referencia al vector que el ciclo for contiene evita la modificación simultánea de todo el vector.

Usar un enum para almacenar múltiples tipos

Los vectores solo pueden almacenar valores del mismo tipo. Esto puede ser inconveniente; definitivamente hay casos de uso para necesitar almacenar una lista de elementos de diferentes tipos. Afortunadamente, las variantes de un enum se definen bajo el mismo tipo de enum, por lo que cuando necesitamos que un tipo represente elementos de diferentes tipos, ¡podemos definir y usar un enum!

Por ejemplo, digamos que queremos almacenar en una lista los elementos de una tabla de hoja de cálculo: algunas columnas pueden contener números, y otras cadenas de texto. Podemos definir un enum cuyas variantes contendrán los diferentes tipos de datos, y todas las variantes se considerarán del mismo tipo: el del enum. Luego podemos crear un vector para contener ese enum y, por lo tanto, en última instancia, contener diferentes tipos. Hemos demostrado esto en el listado 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust necesita saber qué tipos habrá en el vector en tiempo de compilación para saber exactamente cuánta memoria en el montón se necesitará para almacenar cada elemento. También debemos ser explícitos sobre qué tipos están permitidos en este vector. Si Rust permitiera que un vector contenga cualquier tipo, existiría la posibilidad de que uno o más de los tipos causaran errores con las operaciones realizadas en los elementos del vector. Usar un enum más una expresión match significa que Rust se asegurará en tiempo de compilación de que se maneje cada caso posible, como se discutió en el Capítulo 6.

Si tu no sabes el conjunto exhaustivo de tipos que un programa obtendrá en tiempo de ejecución para almacenar en un vector, la técnica de enum no funcionará. En su lugar, puede usar un objeto de rasgo, que cubriremos en el Capítulo 18.

Ahora que hemos discutido algunas de las formas más comunes de usar vectores, asegúrese de revisar la documentación de la API para todos los muchos métodos útiles definidos en Vec<T> por la biblioteca estándar. Por ejemplo, además de push, un método pop elimina y devuelve el último elemento.

Liberar un vector libera sus elementos

Como cualquier otro struct, un vector se libera cuando sale del ámbito, como se anota en el listado 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

Cuando se libera el vector, también se libera todo su contenido, lo que significa que se limpiarán los enteros que contiene. El borrow checker garantiza que cualquier referencia al contenido de un vector solo se utilice mientras el vector en sí sea válido.

Pasemos al siguiente tipo de colección: ¡String!

Almacenando texto codificado en UTF-8 con Strings

Hemos hablado de strings en el Capítulo 4, pero las veremos con más detalle Los nuevos Rustaceans suelen quedarse atascados en las cadenas por una combinación de tres razones: la propensión de Rust a exponer posibles errores, los strings son una estructura de datos más complicada de lo que muchos programadores le dan crédito, y UTF-8. Estos factores se combinan de una manera que puede parecer difícil cuando se viene de otros lenguajes de programación.

Discutiremos strings en el contexto de las colecciones porque las strings se implementan como una colección de bytes, más algunos métodos para proporcionar funcionalidad útil cuando esos bytes se interpretan como texto. En esta sección, hablaremos sobre las operaciones en String que cada tipo de colección tiene, como crear, actualizar y leer. También discutiremos las formas en que String es diferente de las otras colecciones, es decir, cómo indexar en un String se complica por las diferencias entre cómo las personas y las computadoras interpretan los datos de String.

¿Qué es un string?

Bien primero definamos lo que queremos decir con el término string. Rust solo tiene un tipo de string en el lenguaje principal, que es el string slice str que generalmente se ve en su forma prestada &str. En el Capítulo 4, hablamos sobre string slices, que son referencias a algunos datos de cadena codificados en UTF-8 almacenados en otro lugar. Las literales de cadena, por ejemplo, se almacenan en el binario del programa y, por lo tanto, son trozos de cadena.

El tipo String, que es proporcionado por la biblioteca estándar en lugar de codificado en el lenguaje principal, es un tipo de cadena que puede crecer, mutable, de propiedad, codificado en UTF-8. Cuando los Rustaceans se refieren a "strings" en Rust, pueden estar refiriéndose a cualquiera de los tipos String o str, no solo a uno de esos tipos. Aunque esta sección trata principalmente de String, ambos tipos se usan mucho en la biblioteca estándar de Rust, y tanto String como las rebanadas de cadena son codificadas en UTF-8.

Creando un nuevo String

Muchas de las mismas operaciones disponibles con Vec<T> también están disponibles con String, ya que String se implementa en realidad como un envoltorio alrededor de un vector de bytes con algunas garantías, restricciones y capacidades adicionales. Un ejemplo de una función que funciona de la misma manera con Vec<T> y String es la función new para crear una instancia, que se muestra en el listado 8-11.

fn main() {
    let mut s = String::new();
}

Esta línea crea un nuevo String vacío llamado s, el cual podemos luego cargar con datos. A menudo, tendremos algunos datos iniciales que queremos comenzar en el string. Para eso, usamos el método to_string, que está disponible en cualquier tipo que implemente el trait Display, como lo hacen los String Literals. El listado 8-12 muestra dos ejemplos.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // the method also works on a literal directly:
    let s = "initial contents".to_string();
}

Este código crea un string que contiene initial contents.

Podemos también usar la función String::from para crear un String a partir de un string literal. El código en el listado 8-13 es equivalente al código del listado 8-12 que usa to_string.

fn main() {
    let s = String::from("initial contents");
}

Debido a que los strings se usan para muchas cosas, podemos usar muchas APIs genéricas diferentes para strings, lo que nos proporciona muchas opciones. Algunos de ellos pueden parecer redundantes, ¡pero todos tienen su lugar! En este caso, String::from y to_string hacen lo mismo, por lo que elegir depende del estilo y la legibilidad.

Recuerda que los strings son UTF-8 codificados, por lo que podemos incluir cualquier dato codificado correctamente en ellos, Como se muestra en el listado 8-14.

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Todos estos strings son valores válidos de String.

Actualizando un String

Un String puede crecer en tamaño y su contenido puede cambiar, al igual que el contenido de un Vec<T>, si se introducen más datos en el. Además, puedes usar convenientemente el operador + o el macro format! para concatenar valores de String.

Agregando a un String con push_str y push

Podemos hacer crecer un String usando el método push_str para agregar un string slice, como se muestra en el listado 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

Después de estas dos líneas, s contendrá foobar. El método push_str toma un string slice porque no necesariamente queremos tomar posesión del parámetro. Por ejemplo, en el código del listado 8-16, queremos poder usar s2 después de agregar su contenido a s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

Si el método push_str tomara posesión de s2, no podríamos imprimir su valor en la última línea. ¡Sin embargo, este código funciona como esperamos!

El método push toma un solo carácter como parámetro y lo agrega al String. El listado 8-17 agrega la letra l a un String usando el método push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

Como resultado, s contendrá lol.

Concatenacion con el operador + o la Macro format!

A menudo, querrás combinar dos cadenas existentes. Una forma de hacerlo es usar el operador +, como se muestra en el Listado 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

El string s3 contendrá Hello, world!. La razón por la que s1 ya no es válido después de la adición, y la razón por la que usamos una referencia a s2, tiene que ver con la firma del método que se llama cuando usamos el operador +. El operador + usa el método add, cuya firma se ve algo como esto:

fn add(self, s: &str) -> String {

En la biblioteca estándar, verás add definido usando genéricos y tipos asociados. Aquí, hemos sustituido tipos concretos, que es lo que sucede cuando llamamos a este método con valores String. Discutiremos los genéricos en el Capítulo 10. Esta firma nos da las pistas que necesitamos para entender las partes complicadas del operador +.

Primero, s2 tiene un &, lo que significa que estamos agregando una referencia del segundo string al primer string. Esto se debe al parámetro s en la función add: solo podemos agregar un &str a un String; no podemos agregar dos valores String juntos. Pero espera, el tipo de &s2 es &String, no &str, como se especifica en el segundo parámetro de add. ¿Entonces por qué compila el listado 8-18?

La razón por la que podemos usar s2 en la llamada a add es que el compilador puede convertir el argumento &String en un &str. Cuando
llamamos al método add, Rust usa una coerción de dereferencia, que aquí convierte &s2 en &s2[..]. Discutiremos la coerción de dereferencia con más detalle en el Capítulo 15. Debido a que add no toma posesión del parámetro s, s2 seguirá siendo un String válido después de esta operación.

En segundo lugar, podemos ver en la firma que add toma el ownership de self, porque self no tiene un &. Esto significa que s1 en el listado 8-18 se moverá a la llamada de add y ya no será válido después de eso. Entonces, aunque let s3 = s1 + &s2; parece que copiará ambos strings y creará uno nuevo, esta declaración realmente toma posesión de s1, agrega una copia del contenido de s2 y luego devuelve la propiedad del resultado. En otras palabras, parece que está haciendo muchas copias, pero no lo está; la implementación es más eficiente que copiar.

Si necesitamos concatenar múltiples strings, el comportamiento del operador + se vuelve difícil de manejar:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

En este punto, s contendrá tic-tac-toe. Con todos los caracteres + y " es difícil ver qué está pasando. Para una combinación de cadenas más complicada, podemos usar la macro format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

Este código también establece s en tic-tac-toe. La macro format! funciona como println!, pero en lugar de imprimir la salida en la pantalla, devuelve un String con el contenido. La versión del código que usa format! es mucho más fácil de leer, y el código generado por la macro format! usa referencias para que esta llamada no tome posesión de ninguno de sus parámetros.

Indexando en Strings

En muchos otros lenguajes de programación, acceder a caracteres individuales en un string referenciándolos por índice es una operación válida y común. Sin embargo, si intentas acceder a partes de un String usando la sintaxis de indexación en Rust, obtendrás un error. Considera el código inválido en el listado 8-19.

fn main() {
    let s1 = String::from("hello");
    let h = s1[0];
}

Este código dará como resultado el siguiente error:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = help: the trait `SliceIndex<str>` is not implemented for `{integer}`, which is required by `String: Index<_>`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the trait `SliceIndex<[_]>` is implemented for `usize`
  = help: for that trait implementation, expected `[_]`, found `str`
  = note: required for `String` to implement `Index<{integer}>`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` (bin "collections") due to 1 previous error

El error y la nota cuentan la historia: los strings de Rust no admiten indexación. Pero, ¿por qué no? Para responder a esa pregunta, necesitamos discutir cómo Rust almacena los strings en la memoria.

Representación Interna

Un String es un wrapper sobre un Vec<u8>. Veamos algunos de nuestros strings de ejemplo UTF-8 correctamente codificados del listado 8-14. Primero, este:

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

En este caso, len será 4, lo que significa que el vector que almacena el string “Hola” tiene 4 bytes de largo. Cada una de estas letras toma un byte cuando se codifica en UTF-8. La siguiente línea, sin embargo, puede sorprenderte. (Nota que este string comienza con la letra cirílica Ze mayúscula, no con el número árabe 3.)

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

Si tu te preguntas que tan largo es el string, podrías decir 12. De hecho, la respuesta de Rust es 24: ese es el número de bytes que se necesitan para codificar “Здравствуйте” en UTF-8, porque cada valor escalar Unicode en ese string toma 2 bytes de almacenamiento. Por lo tanto, un índice en los bytes del string no siempre se correlacionará con un valor escalar Unicode válido. Para demostrarlo, considera este código inválido de Rust:

let hello = "Здравствуйте";
let answer = &hello[0];

Tu Ahora sabes que answer no será З, la primera letra. Cuando codificado en UTF-8, el primer byte de З es 208 y el segundo es 151, por lo que parecería que answer debería ser 208, pero 208 no es un carácter válido por sí solo. Devolver 208 probablemente no sea lo que un usuario querría si pidieran la primera letra de esta cadena; sin embargo, esos son los únicos datos que Rust tiene en el índice de bytes 0. Los usuarios generalmente no quieren que se devuelva el valor de byte, incluso si la cadena contiene solo letras latinas: si &"hi"[0] fuera un código válido que devolviera el valor de byte, devolvería 104, no h.

La respuesta, entonces, es que para evitar devolver un valor inesperado y causar errores que podrían no descubrirse de inmediato, Rust no compila este código en absoluto y evita malentendidos al comienzo del proceso de desarrollo.

Bytes, valores escalares y grupos de grafemas

Otro punto sobre UTF-8 es que hay tres formas relevantes de ver las cadenas desde la perspectiva de Rust: como bytes, valores escalares y grupos de grafemas (lo más parecido a lo que llamaríamos letras).

Si observamos la palabra “नमस्ते” en escritura Devanagari, se almacena como un vector de valores u8 que se ve así:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

Eso es 18 bytes y es como las computadoras almacenan los datos. Si los observamos como valores escalares Unicode, que es lo que es el tipo char de Rust, esos bytes se ven así:

['न', 'म', 'स', '्', 'त', 'े']

Aquí hay seis valores char, pero el cuarto y el sexto no son letras: son diacríticos que no tienen sentido por sí mismos. Finalmente, si los miramos como grupos de grafemas, obtendríamos lo que una persona llamaría las cuatro letras que componen la palabra hindi:

["न", "म", "स्", "ते"]

Rust proporciona diferentes formas de interpretar los datos de string sin procesar que las computadoras almacenan para que cada programa pueda elegir la interpretación que necesita, sin importar en qué idioma humano estén los datos.

Una última razón por la que Rust no permite indexar en un String para obtener un carácter es que se espera que las operaciones de indexación siempre tomen tiempo constante (O(1)). Pero no es posible garantizar ese rendimiento con un String, porque Rust tendría que recorrer el contenido desde el principio hasta el índice para determinar cuántos caracteres válidos había.

Slicing Strings

La indexación en un String suele ser una mala idea porque no está claro cuál debería ser el tipo de retorno de la operación de indexación de string: un valor de byte, un carácter, un grupo de grafemas o una rebanada de string. Si realmente necesita usar índices para crear rebanadas de string, por lo tanto, Rust le pide que sea más específico.

En lugar de indexar usando [] con un solo número, puede usar [] con un rango para crear un string slice conteniendo bytes particulares:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

Aquí, s será un &str que contiene los primeros cuatro bytes del string. Antes, mencionamos que cada uno de estos caracteres era de dos bytes, lo que significa que s será Зд.

Si intentáramos hacer un slice con solo una parte de los bytes de un carácter, algo como &hello[0..1], Rust entraría en pánico en tiempo de ejecución de la misma manera que si se accediera a un índice no válido en un vector:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`
thread 'main' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Debemos tener cuidado cuando creamos string slices, porque hacerlo puede bloquear su programa.

Métodos para iterar sobre Strings

La mejor manera de operar en partes de strings es ser explícito sobre si desea caracteres o bytes. Para valores escalares Unicode individuales, use el método chars. Llamar a chars en “Зд” separa y devuelve dos valores de tipo char, y puede iterar sobre el resultado para acceder a cada elemento:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

Este código imprimirá lo siguiente:

З
д

Alternativamente, el método bytes devuelve cada byte sin procesar, que puede ser apropiado para su dominio:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

Este código imprimirá los cuatro bytes que componen el string:

208
151
208
180

Pero asegúrate de recordar que los valores escalares de Unicode válidos pueden estar compuestos por más de un byte.

Obtener grupos de grafemas a partir de cadenas, como en el caso del alfabeto Devanagari, es complejo, por lo que esta funcionalidad no está proporcionada por la biblioteca estándar. Hay paquetes disponibles en crates.io si necesitas esta funcionalidad.

Los Strings no son tan simples

Para resumir, los strings son complicados. Los diferentes lenguajes de programación hacen diferentes elecciones sobre cómo presentar esta complejidad al programador. Rust ha elegido hacer que el manejo correcto de los datos String sea el comportamiento predeterminado para todos los programas de Rust, lo que significa que los programadores tienen que pensar más en el manejo de datos UTF-8 por adelantado. Este compromiso expone más de la complejidad de las cadenas de lo que parece en otros lenguajes de programación, pero evita que tenga que manejar errores que involucran caracteres no ASCII más adelante en su ciclo de vida de desarrollo.

La buena noticia es que la biblioteca estándar ofrece mucha funcionalidad construida a partir de los tipos String y &str para ayudar a manejar estas situaciones complejas correctamente. Asegúrese de consultar la documentación para obtener métodos útiles como contains para buscar en un string y replace para sustituir partes de un string por otro string.

Pasemos a algo un poco menos complejo: ¡Hash Maps!

Almacenar Claves con Valores Asociados en HashMaps

La última de nuestras colecciones comunes es el hash map. El tipo HashMap<K, V> almacena un mapeo de claves de tipo K a valores de tipo V usando una función hash, que determina cómo coloca estas claves y valores en la memoria. Muchos lenguajes de programación admiten este tipo de estructura de datos, pero a menudo usan un nombre diferente, como hash, map, object, hash table, diccionario o arreglos asociativos, solo para nombrar algunos.

Los hash maps son útiles cuando desea buscar datos no usando un índice, como puede hacerlo con vectores, sino usando una clave que puede ser de cualquier tipo. Por ejemplo, en un juego, podría realizar un seguimiento de la puntuación de cada equipo en un hash map en el que cada clave es el nombre de un equipo y los valores son la puntuación de cada equipo. Dado un nombre de equipo, puede recuperar su puntuación.

Repasaremos la API básica de los hash maps en esta sección, pero muchas más cosas buenas se esconden en las funciones definidas en HashMap<K, V> por la biblioteca estándar. Como siempre, consulte la documentación de la biblioteca estándar para obtener más información.

Creando un nuevo HashMap

Una forma de crear un hash map vacío es usar new y agregar elementos con insert. En el Listado 8-20, estamos realizando un seguimiento de las puntuaciones de dos equipos cuyos nombres son Blue y Yellow. El equipo Blue comienza con 10 puntos y el equipo Yellow comienza con 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Ten en cuenta que es importante importar primero el módulo HashMap de la biblioteca estándar de colecciones. De nuestras tres colecciones comunes, ésta es la menos utilizada, por lo que no se incluye automáticamente en las características del prelude. Además, los hash maps tienen menos soporte por parte de la biblioteca estándar; por ejemplo, no hay una macro incorporada para construirlos.

Al igual que los vectores, los hash maps almacenan sus datos en el heap. Este HashMap tiene claves de tipo String y valores de tipo i32. Al igual que los vectores, los hash maps son homogéneos: todas las claves deben tener el mismo tipo entre sí y todos los valores deben tener el mismo tipo.

Accediendo a los valores en un HashMap

Podemos obtener un valor de un hash map proporcionando su clave al método get como se muestra en el listado 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

Aquí, score tendrá el valor que está asociado con el equipo Blue, y el resultado será 10. El método get devuelve un Option<&V>; si no hay un valor para ese clave en el hash map, get devolverá None. Este programa maneja un Option llamando a copied para obtener un Option<i32> en lugar de un Option<&i32>, luego unwrap_or para establecer score en cero si scores no tiene una entrada para la clave.

Podemos iterar sobre cada par clave-valor en un hash map de manera similar a como lo hacemos con vectores, usando un ciclo for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

Este código imprimirá cada par en un orden arbitrario:

Yellow: 50
Blue: 10

HashMaps y Ownership

Para los tipos que implementan el trait Copy, como i32, los valores se copian en el hash map. Para valores de propiedad como String, los valores se moverán y el hash map será el propietario de esos valores, como se demuestra en el listado 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

No podemos usar field_name y field_value después de que se hayan movido al hash map con la llamada a insert.

Si insertamos referencias a valores en el hash map, los valores no se moverán al hash map. Los valores a los que apuntan las referencias deben ser válidos al menos mientras el hash map sea válido. Hablaremos más sobre estos problemas en la sección “Validando referencias con Lifetimes” en el Capítulo 10.

Actualizando un HashMap

Aunque la cantidad de pares clave/valor es creciente, cada clave única solo puede tener un valor asociado con ella a la vez (pero no viceversa: por ejemplo, el equipo Blue y el equipo Yellow podrían tener el valor 10 almacenados en el hash map scores).

Cuando queremos cambiar los datos en un hash map, tenemos que decidir cómo manejar el caso en el que una clave ya tiene un valor asignado. Podrías reemplazar el valor antiguo por el nuevo valor, ignorando completamente el valor antiguo. Podrías mantener el valor antiguo e ignorar el nuevo valor, agregando el nuevo valor solo si la clave no tiene ya un valor. O podrías combinar el valor antiguo y el nuevo valor. ¡Veamos cómo hacer cada una de estas!

Reemplazando un valor

Si insertamos una clave y un valor en un hash map y luego insertamos esa misma clave con un valor diferente, el valor asociado con esa clave se reemplazará. Aunque el código en el listado 8-23 llama a insert dos veces, el hash map solo contendrá un par clave-valor porque estamos insertando el valor para la clave del equipo Blue dos veces.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

    println!("{scores:?}");
}

Este código imprimirá {"Blue": 25}. El valor original de 10 ha sido sobrescrito.

Insertando una clave y un valor solo si una clave no está presente

Es común verificar si una clave en particular ya existe en el hash map con un valor y luego realizar las siguientes acciones: si la clave existe en el hash map, el valor existente debe permanecer tal como está; si la clave no existe, insertarla junto con su valor.

Los hash maps tienen una API especial para esto llamada entry que toma la clave que desea verificar como parámetro. El valor de retorno del método entry es un enum llamado Entry que representa un valor que puede o no existir. Digamos que queremos verificar si la clave para el equipo Yellow tiene un valor asociado. Si no lo tiene, queremos insertar el valor 50, y lo mismo para el equipo Blue. Usando la API entry, el código se ve como el listado 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

    println!("{scores:?}");
}

El método or_insert en Entry está definido para devolver una referencia mutable al valor correspondiente a la clave Entry si esa clave existe, y si no, inserta el parámetro como el nuevo valor para esta clave y devuelve una referencia mutable al nuevo valor. Esta técnica es mucho más limpia que escribir la lógica nosotros mismos y, además, juega mejor con el borrow checker.

Ejecutar el código en el listado 8-24 imprimirá {"Yellow": 50, "Blue": 10}. La primera llamada a entry insertará la clave para el equipo Yellow con el valor 50 porque el equipo Yellow no tiene un valor todavía. La segunda llamada a entry no cambiará el hash map porque el equipo Blue ya tiene el valor 10.

Actualizando un valor basado en el valor anterior

Otro caso común para los hash maps es buscar un valor para una clave y luego actualizar ese valor en función del valor anterior. Por ejemplo, el listado 8-25 muestra un código que cuenta cuántas veces aparece cada palabra en algún texto. Usamos un hash map con las palabras como claves y aumentamos el valor para mantener un recuento de cuántas veces hemos visto esa palabra. Si es la primera vez que vemos una palabra, primero insertaremos el valor 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{map:?}");
}

Este código imprimirá {"world": 2, "hello": 1, "wonderful": 1}. Es posible que veas los mismos pares clave-valor en un orden diferente: recuerda la sección “Accediendo a valores en un hash map” que iterar sobre un hash map ocurre en un orden arbitrario.

El método split_whitespace devuelve un iterator sobre sub-slices, separados por espacios en blanco, del valor en text. El método or_insert devuelve una referencia mutable (&mut V) al valor para la clave especificada. Aquí, almacenamos esa referencia mutable en la variable count, por lo que para asignar a ese valor, primero debemos desreferenciar count usando el asterisco (*). La referencia mutable sale del ámbito al final del ciclo for, por lo que todos estos cambios son seguros y permitidos por las reglas del borrowing.

Funciones de Hashing

Por defecto, HashMap usa una función de hashing llamada SipHash que puede proporcionar resistencia a ataques de Denegación de Servicio (DoS) que involucran tablas hash¹. Este no es el algoritmo de hashing más rápido disponible, pero el compromiso por una mejor seguridad que viene con la caída en el rendimiento vale la pena. Si perfilas tu código y encuentras que la función de hash predeterminada es demasiado lenta para tus propósitos, puedes cambiar a otra función especificando un hasher diferente. Un hasher es un tipo que implementa el trait BuildHasher. Hablaremos sobre traits y cómo implementarlos en el Capítulo 10. No necesariamente tienes que implementar tu propio hasher desde cero; crates.io tiene bibliotecas compartidas por otros usuarios de Rust que proporcionan hashes que implementan muchos algoritmos de hashing comunes.

Resumen

Los vectores, los strings y los hash maps proporcionan una funcionalidad importante que necesitarás cuando quieras almacenar, acceder y modificar datos. Aquí hay algunos ejercicios que ahora deberías estar equipado para resolver:

1. Dada una lista de enteros, usa un vector y devuelve la mediana (cuando se ordena, el valor en la posición media) y la moda (el valor que ocurre con más frecuencia; un hash map será útil aquí) de la lista.
2. Convierte strings a pig latin. La primera consonante de cada palabra se mueve al final de la palabra y se agrega "ay", por lo que "primero" se convierte en "rimepay". Sin embargo, si la palabra comienza con una vocal, simplemente agregue "hay" al final de la palabra ("manzanaay"). ¡Ten en cuenta las reglas de UTF-8!
3. Usando un hash map y vectores, cree un texto de interfaz para permitir que un usuario agregue nombres de empleados a un departamento en una empresa. Por ejemplo, "Agregar Sally a Ingeniería" o "Agregar Amir a Ventas". Luego, permita que el usuario recupere una lista de todas las personas en un departamento o todas las personas en la empresa por departamento, ordenadas alfabéticamente.

La documentación de la biblioteca estándar describe métodos que los vectores, strings y hash maps tienen que ser útiles para estos ejercicios.

Nos estamos adentrando en programas más complejos en los que las operaciones pueden fallar, por lo que es un momento perfecto para discutir el manejo de errores. ¡Haremos eso a continuación!

Manejo de Errores

Los errores son un hecho de la vida en el software, por lo que Rust tiene una serie de características para manejar situaciones en las que algo sale mal. En muchos casos, Rust te obliga a reconocer la posibilidad de un error y tomar alguna acción antes de que tu código se compile. ¡Este requisito hace que su programa sea más robusto al garantizar que descubrirá errores y los manejará adecuadamente antes de implementar su código en producción!

Rust agrupa los errores en dos categorías principales: errores recuperables e irrecuperables. Para un error recuperable, como un error de archivo no encontrado, lo más probable es que solo queramos informar el problema al usuario y volver a intentar la operación. Los errores irreversibles siempre son síntomas de errores, como intentar acceder a una ubicación más allá del final de un arreglo, por lo que queremos detener inmediatamente el programa.

La mayoría de los lenguajes no distinguen entre estos dos tipos de errores y los manejan de la misma manera, utilizando mecanismos como excepciones. Rust no tiene excepciones. En cambio, tiene el tipo Result<T, E> para errores recuperables y el macro panic! que detiene la ejecución cuando el programa encuentra un error irrecuperable. Este capítulo cubre primero la llamada a panic! y luego habla sobre la devolución de valores Result<T, E>. Además, exploraremos consideraciones al decidir si intentar recuperarse de un error o detener la ejecución.

Errores irrecuperables con panic!

A veces, sucede algo malo en su código y no hay nada que pueda hacer al respecto. En estos casos, Rust tiene la macro panic!. Hay dos formas de causar un panic en la práctica: tomando una acción que hace que nuestro código entre en pánico (como acceder a un arreglo más allá del final) o llamando explícitamente a la macro panic!. En ambos casos, causamos un pánico en nuestro programa. De forma predeterminada, estos pánicos imprimirán un mensaje de error, se desharán, limpiarán la pila y se cerrarán. A través de una variable de entorno, también puede hacer que Rust muestre la pila de llamadas cuando ocurre un pánico para facilitar el seguimiento de la fuente del panic.

Deshacer la pila o abortar en respuesta a un pánico

Por defecto, cuando ocurre un panic, el programa comienza a deshacerse, lo que significa que Rust retrocede por la pila y limpia los datos de cada función que encuentra. Sin embargo, este retroceso y limpieza es mucho trabajo. Rust, por lo tanto, le permite elegir la alternativa de abortar inmediatamente, lo que termina el programa sin limpiar.

La memoria que el programa estaba usando deberá ser limpiada por el sistema operativo. Si en su proyecto necesita hacer que el binario resultante sea lo más pequeño posible, puede cambiar de deshacer el programa a abortarlo al producir un pánico agregando panic = 'abort' a las secciones [profile] apropiadas en su archivo Cargo.toml. Por ejemplo, si desea abortar en caso de pánico en el modo de lanzamiento, agregue esto:

[profile.release]
panic = 'abort'

Intentemos llamar un panic! en un programa simple:

fn main() {
    panic!("crash and burn");
}

Cuando ejecutes el programa, verás algo como esto:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`
thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

La llamada a panic! causa el mensaje de error contenido en las dos últimas líneas. La primera línea muestra nuestro mensaje de panic y el lugar en nuestro código fuente donde ocurrió el panic: src/main.rs:2:5 indica que es la segunda línea, quinto carácter de nuestro archivo src/main.rs.

En este caso, la línea indicada es parte de nuestro código, y si vamos a esa línea, vemos la llamada a la macro panic!. En otros casos, la llamada a panic! podría estar en el código que nuestro código llama, y el nombre de archivo y el número de línea informados por el mensaje de error serán el código de otra persona donde se llama a la macro panic!, no la línea de nuestro código que finalmente condujo a la llamada a panic!. Podemos usar el backtrace de las funciones de las que provino la llamada a panic! para determinar la parte de nuestro código que está causando el problema. Discutiremos el backtrace en más detalle a continuación.

Usando el backtrace de panic!

Podemos usar el rastreo de llamadas (backtrace) de las funciones desde donde se originó la llamada a panic! para identificar la parte de nuestro código que está causando el problema. Para entender cómo usar un backtrace de panic!, veamos otro ejemplo y analicemos qué ocurre cuando una llamada a panic! proviene de una biblioteca debido a un error en nuestro código, en lugar de que sea nuestro código llamando directamente a la macro. El Listado 9-1 contiene código que intenta acceder a un índice en un vector fuera del rango de índices válidos.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

Aquí, estamos intentando acceder al elemento 100 de nuestro vector (que está en el índice 99 porque el indexado comienza en cero), pero el vector solo tiene 3 elementos. En esta situación, Rust entrará en pánico. Usar [] se supone que devuelve un elemento, pero si pasa un índice no válido, no hay ningún elemento que Rust podría devolver aquí que sea correcto.

En C, intentar leer más allá del final de una estructura de datos es un undefined. Podría obtener lo que está en la ubicación de memoria que correspondería a ese elemento en la estructura de datos, aunque la memoria no pertenece a esa estructura. Esto se llama buffer overread y puede provocar vulnerabilidades de seguridad si un atacante puede manipular el índice de tal manera que lea datos que no debería estar permitido que se almacenen después de la estructura de datos.

Para proteger su programa de este tipo de vulnerabilidad, si intenta leer un elemento en un índice que no existe, Rust detendrá la ejecución y se negará a continuar. Intentémoslo y veamos:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Este error apunta a la línea 4 de nuestro main.rs donde intentamos acceder al índice 99 de el vector v.

La siguiente línea de nota nos dice que podemos establecer la variable de entorno RUST_BACKTRACE para obtener el backtrace de exactamente lo que sucedió para causar el error. El Backtrace es una lista de todas las funciones que se han llamado para llegar a este punto. El backtrace en Rust funciona como lo hacen en otros lenguajes: la clave para leer el backtrace es comenzar desde la parte superior y leer hasta que vea archivos que escribió. Ese es el lugar donde se originó el problema. Las líneas por encima de ese punto son el código que su código ha llamado; las líneas a continuación son el código que llamó a su código. Estas líneas antes y después pueden incluir código de Rust core, código de biblioteca estándar o crates que estés usando. Intentemos obtener el backtrace estableciendo la variable de entorno RUST_BACKTRACE a cualquier valor excepto 0. El listado 9-2 muestra una salida similar a la que verás.

$ export RUST_BACKTRACE=1; cargo run
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/std/src/panicking.rs:662:5
   1: core::panicking::panic_fmt
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/panicking.rs:74:14
   2: core::panicking::panic_bounds_check
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/panicking.rs:276:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/slice/index.rs:302:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/vec/mod.rs:2920:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

¡Eso es mucho resultado! La salida exacta que vea puede ser diferente según su sistema operativo y la versión de Rust. Para obtener el backtrace con esta información, deben estar habilitados los símbolos de depuración. Los símbolos de depuración están habilitados de forma predeterminada cuando se usa cargo build o cargo run sin el indicador --release, como tenemos aquí.

En la salida en el listado 9-2, la línea 6 del backtrace apunta a la línea en nuestro proyecto que está causando el problema: la línea 4 de src/main.rs. Si no queremos que nuestro programa entre en pánico, debemos comenzar nuestra investigación en la ubicación señalada por la primera línea que menciona un archivo que escribimos. En la listado 9-1, donde escribimos deliberadamente un código que entraría en pánico, la forma de solucionar el pánico es no solicitar un elemento más allá del rango de los índices del vector. Cuando su código entra en pánico en el futuro, deberá averiguar qué acción está tomando el código con qué valores para causar el pánico y qué debería hacer el código en su lugar.

¡Volveremos a panic! y cuándo deberíamos y no deberíamos usar panic! para manejar las condiciones de error en la sección “To panic! or Not to panic!” más adelante en este capítulo. A continuación, veremos cómo recuperarnos de un error usando Result.

Errores recuperables con Result

La mayoría de los errores no son lo suficientemente graves como para requerir que el programa se detenga por completo. A veces, cuando una función falla, es por una razón que puede interpretar y responder fácilmente. Por ejemplo, si intenta abrir un archivo y esa operación falla porque el archivo no existe, es posible que desee crear el archivo en lugar de terminar el proceso.

Recordemos el capítulo “Manejo de fallas potenciales con Result” en el Capítulo 2 que el enum Result se define como tener dos variantes, Ok y Err, de la siguiente manera:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T y E son parámetros de tipo genérico: hablaremos de los genéricos con más detalle en el Capítulo 10. Lo que necesita saber ahora es que T representa el tipo del valor que será devuelto en un caso de éxito dentro de la variante Ok, y E representa el tipo del error que será devuelto en un caso de fallo dentro de la variante Err. Debido a que Result tiene estos parámetros de tipo genérico, podemos usar el tipo Result y las funciones definidas en él en muchas situaciones diferentes donde el valor de éxito y el valor de error que queremos devolver pueden diferir.

Llamemos a una función que devuelve un valor Result porque la función podría fallar. En el listado 9-3 intentamos abrir un archivo.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

El tipo de retorno de File::open es un Result<T, E>. El parámetro genérico T ha sido llenado por la implementación de File::open con el tipo del valor de éxito, std::fs::File, que es un manejador de archivo. El tipo de E utilizado en el valor de error es std::io::Error. Este tipo de retorno significa que la llamada a File::open podría tener éxito y devolver un manejador de archivo del que podemos leer o escribir. La llamada a la función también podría fallar: por ejemplo, el archivo podría no existir, o podríamos no tener permiso para acceder al archivo. La función File::open necesita tener una forma de decirnos si tuvo éxito o falló y al mismo tiempo darnos el manejador de archivo o la información de error. Esta información es exactamente lo que transmite el enum Result.

En el caso en que File::open tenga éxito, el valor en la variable greeting_file_result será una instancia de Ok que contiene un manejador de archivo. En el caso en que falla, el valor en greeting_file_result será una instancia de Err que contiene más información sobre el tipo de error que ocurrió.

Necesitamos agregar al código en el listado 9-3 para tomar diferentes acciones dependiendo del valor que File::open devuelve. El listado 9-4 muestra una forma de manejar él Result usando una herramienta básica, la expresión match que discutimos en el Capítulo 6.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {error:?}"),
    };
}

Ten en cuenta que, al igual que el enum Option, el enum Result y sus variantes se han traído al ámbito por el prelude, por lo que no necesitamos especificar Result:: antes de las variantes Ok y Err en las opciones de match.

Cuando el result es Ok, este código devolverá el valor interno file fuera de la variante Ok, y luego asignaremos ese valor de manejador de archivo a la variable greeting_file. Después del match, podemos usar el manejador de archivo para leer o escribir.

La otra opción en el match es Err, que significa que el File::open ha fallado y el valor interno err de la variante Err contendrá información sobre cómo o por qué falló File::open. En este caso, llamamos a la función panic! y pasamos el valor err al panic!. Esto causa que nuestro programa se bloquee y muestre el mensaje de error que panic! proporciona. Si ejecutamos este código, obtendremos el siguiente mensaje de error:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`
thread 'main' panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Como de costumbre, esta salida nos dice exactamente qué ha salido mal.

Haciendo coincidir diferentes errores

El código en el listado 9-4 será panic! no importa por qué File::open falló. Sin embargo, queremos tomar diferentes acciones para diferentes razones de falla: si File::open falló porque el archivo no existe, queremos crear el archivo y devolver el manejador del nuevo archivo. Si File::open falló por cualquier otra razón, por ejemplo, porque no teníamos permiso para abrir el archivo, todavía queremos que el código dispare el panic! de la misma manera que lo hizo en el listado 9-4. Para esto agregamos una expresión match interna, que se muestra en el listado 9-5.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            other_error => {
                panic!("Problem opening the file: {other_error:?}");
            }
        },
    };
}

El tipo de valor que File::open devuelve dentro de la variante Err es io::Error, que es una estructura proporcionada por la biblioteca estándar. Esta estructura tiene un método kind que podemos llamar para obtener un valor io::ErrorKind. El enum io::ErrorKind es proporcionado por la biblioteca estándar y tiene variantes que representan los diferentes tipos de errores que podrían resultar de una operación io. La variante que queremos usar es ErrorKind::NotFound, que indica que el archivo que estamos tratando de abrir aún no existe. Así que hacemos coincidir en greeting_file_result, pero también tenemos una coincidencia interna en error.kind().

La condición que queremos verificar en la coincidencia interna es si el valor devuelto por error.kind() es la variante NotFound del enum ErrorKind. Si es así, intentamos crear el archivo con File::create. Sin embargo, debido a que File::create también podría fallar, necesitamos una segunda opción en la expresión match interna. Cuando no se puede crear el archivo, se imprime un mensaje de error diferente. La segunda opción del match externo permanece igual, por lo que el programa se bloquea en cualquier error además del error de archivo faltante.

Alternativas a usar match con Result<T, E>

¡Eso es mucho match! La expresión match es útil, pero también es bastante verbosa. En el Capítulo 13 aprenderás sobre los closures, que se usan con muchos de los métodos definidos en Result<T, E>. Estos métodos pueden ser más concisos que usar match al manejar valores Result<T, E> en tu código.

Por ejemplo, aquí hay otra forma de escribir la misma lógica que se muestra en el listado 9-5, esta vez usando closures y el método unwrap_or_else:

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

Aunque este código tiene el mismo comportamiento que el listado 9-5, no contiene ninguna expresión match y es más fácil de leer. Vuelve a este ejemplo después de leer el Capítulo 13, y busca el método unwrap_or_else en la documentación de la biblioteca estándar. Muchos más de estos métodos pueden limpiar enormes expresiones match anidadas cuando se trata de errores.

Atajos para panic en caso de error: unwrap y expect

Usando match funciona bastante bien, pero puede ser un poco verboso y no siempre comunica bien la intención. El tipo Result<T, E> tiene muchos métodos auxiliares definidos en él para hacer varias tareas más específicas. El método unwrap es un método de atajo implementado exactamente como la expresión match que escribimos en el listado 9-4. Si el valor Result es la variante Ok, unwrap devolverá el valor dentro de Ok. Si el Result es la variante Err, unwrap llamará a la macro panic! por nosotros. Aquí hay un ejemplo de unwrap en acción:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

Si ejecutamos este código sin un archivo hello.txt, veremos un mensaje de error de la llamada panic! que el método unwrap hace:

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Del mismo modo, el método expect nos permite elegir el mensaje de error de panic!. Usando expect en lugar de unwrap y proporcionando buenos mensajes de error puede transmitir tu intención y facilitar el seguimiento de la fuente de un pánico. La sintaxis de expect se ve así:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

Nosotros usamos expect de la misma manera que unwrap: para devolver el manejo de archivo o llamar a la macro panic!. El mensaje de error utilizado por expect en su llamada a panic! será el parámetro que pasamos a expect, en lugar del mensaje predeterminado de panic! que usa unwrap. Así es como se ve:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

En producción, la mayoría de los Rustaceans eligen expect en lugar de unwrap y dan más contexto sobre por qué se espera que la operación siempre tenga éxito. De esa manera, si tus suposiciones se demuestran incorrectas, tienes más información para usar en la depuración.

Propagación de errores

Cuando escribes una función cuyo cuerpo puede generar un error, en lugar de manejar el error dentro de la función, puedes devolver el error al código que llamó la función. Esto se conoce como propagación del error y le da más control al código que llama, donde puede haber más información o lógica que dicte cómo se debe manejar el error que la que tienes disponible en el contexto de tu código.

Por ejemplo, El listado 9-6 muestra una función que lee un nombre de usuario de un archivo. Si el archivo no existe o no se puede leer, esta función devolverá esos errores al código que llamó a la función.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}
}

Esta función se puede escribir de una manera mucho más corta, pero vamos a empezar por hacer mucho de ella manualmente para explorar el manejo de errores; al final, mostraremos la forma más corta. Veamos primero el tipo de retorno de la función: Result<String, io::Error>. Esto significa que la función está devolviendo un valor del tipo Result<T, E> donde el parámetro genérico T se ha rellenado con el tipo concreto String, y el tipo genérico E se ha rellenado con el tipo concreto io::Error.

Si esta función tiene éxito sin ningún problema, el código que llama a esta función recibirá un valor Ok que contiene una String - el username que esta función leyó del archivo. Si esta función encuentra algún problema, el código que llama recibirá un valor Err que contiene una instancia de io::Error que contiene más información sobre cuáles fueron los problemas. Elegimos io::Error como el tipo de retorno de esta función porque eso sucede que es el tipo del valor de error devuelto de ambas operaciones que estamos llamando en el cuerpo de esta función que podrían fallar: la función File::open y el método read_to_string.

El cuerpo de la función comienza llamando a la función File::open. Entonces manejamos el valor Result con una expresión match similar a la del Listado 9-4. Si File::open tiene éxito, el archivo manejador en el patrón de variable file se convierte en el valor en la variable de patrón mutable username_file y la función continúa. En el caso de Err, en lugar de llamar a panic!, usamos la palabra clave return para devolver temprano la función por completo y pasar el valor de error de File::open, ahora en la variable de patrón e, de vuelta al código que llama a esta función como el valor de error de esta función.

Entonces, si tenemos un manejador de archivo en username_file, la función crea un nuevo String en la variable username y llama al método read_to_string en el manejador de archivo en username_file para leer el contenido del archivo en username. El método read_to_string también devuelve un Result porque podría fallar, incluso si File::open tuvo éxito. Así que necesitamos otro match para manejar ese Result: si read_to_string tiene éxito, entonces nuestra función ha tenido éxito, y devolvemos el nombre de usuario del archivo que ahora está en username envuelto en un Ok. Si read_to_string falla, devolvemos el valor de error de la misma manera que devolvimos el valor de error en el match que manejó el valor de retorno de File::open. Sin embargo, no necesitamos decir explícitamente return, porque esta es la última expresión de la función.

El código que llama a este código se encargará de obtener un valor Ok que contiene un nombre de usuario o un valor Err que contiene un io::Error. Es responsabilidad del código que llama decidir qué hacer con esos valores. Si el código que llama obtiene un valor Err, podría llamar a panic! y bloquear el programa, usar un nombre de usuario predeterminado o buscar el nombre de usuario en algún lugar que no sea un archivo, por ejemplo. No tenemos suficiente información sobre lo que el código que llama realmente está tratando de hacer, por lo que propagamos toda la información de éxito o error hacia arriba para que la maneje apropiadamente.

Este patrón de propagación de errores es tan común en Rust que Rust proporciona el operador de interrogación ? para hacer esto más fácil.

Un atajo para propagar errores: el operador ?

El listado 9-7 muestra una implementación de read_username_from_file que tiene la misma funcionalidad que en el Listado 9-6, pero esta implementación utiliza el operador ?.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

El ? colocado después de un valor Result se define para funcionar de casi la misma manera que las expresiones match que definimos para manejar los valores Result en el listado 9-6. Si el valor de Result es un Ok, el valor dentro del Ok se devolverá de esta expresión, y el programa continuará. Si el valor es un Err, él Err se devolverá de toda la función como si hubiéramos usado la palabra clave return para que el valor de error se propague al código que llama.

Hay una diferencia entre lo que hace la expresión match del listado 9-6 y lo que hace el operador ?: los valores de error que tienen el operador ? llamado en ellos pasan a través de la función from, definida en el trait From en la biblioteca estándar, que se usa para convertir valores de un tipo a otro. Cuando el operador ? llama a la función from, el tipo de error recibido se convierte en el tipo de error definido en el tipo de retorno de la función actual. Esto es útil cuando una función devuelve un tipo de error para representar todas las formas en que una función podría fallar, incluso si las partes podrían fallar por muchas razones diferentes.

Por ejemplo, podríamos cambiar la función read_username_from_file en el listado 9-7 para devolver un tipo de error personalizado llamado OurError que definimos. Si también definimos impl From<io::Error> for OurError para construir una instancia de OurError a partir de un io::Error, entonces el operador ? llama en el cuerpo de read_username_from_file llamará a from y convertirá los tipos de error sin necesidad de agregar más código a la función.

En el contexto del listado 9-7, el ? al final de la llamada a File::open devolverá el valor dentro de un Ok a la variable username_file. Si ocurre un error, el ? operador devolverá temprano toda la función y dará cualquier valor Err al código que llama. Lo mismo se aplica al ? al final de la llamada a read_to_string.

El operador ? elimina mucho código repetitivo y realiza esta función de implementación más simple. Incluso podríamos acortar aún más este código encadenando llamadas de método inmediatamente después del ?, como se muestra en el Listado 9-8.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

Hemos movido la creación del nuevo String en username al principio de la función; esa parte no ha cambiado. En lugar de crear una variable username_file, hemos encadenado la llamada a read_to_string directamente sobre el resultado de File::open("hello.txt")?. Todavía tenemos un ? al final de la llamada a read_to_string, y todavía devolvemos un valor Ok que contiene username cuando tanto File::open como read_to_string tienen éxito en lugar de devolver errores. La funcionalidad es nuevamente la misma que en el listado 9-6 y el listado 9-7; esta es solo una forma diferente y más ergonómica de escribirla.

El listado 9-9 muestra una forma de hacer esto aún más conciso usando fs::read_to_string.

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

Leer un archivo en un String es una operación bastante común, por lo que la biblioteca estándar proporciona la conveniente función fs::read_to_string que abre el archivo, crea un nuevo String, lee el contenido del archivo, coloca el contenido en ese String y lo devuelve. Por supuesto, usar fs::read_to_string no nos da la oportunidad de explicar todo el manejo de errores, por lo que lo hicimos de la manera más larga primero.

Donde se puede usar el operador ?

El operador ? solo puede usarse en funciones cuyo tipo de retorno sea compatible con el valor que se usa con el operador ?. Porque el operador ? está definido para realizar una devolución temprana de un valor de la función, de la misma manera que la expresión match que definimos en el listado 9-6. En el listado 9-6, el match estaba usando un valor Result, y el brazo de devolución temprana devolvió un valor Err(e). El tipo de retorno de la función debe ser un Result para que sea compatible con este return.

En el listado 9-10, veamos el error que obtendremos si usamos el operador ? en una función main con un tipo de retorno incompatible con el tipo de valor que usamos ?:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

Este código abre un archivo, que puede fallar. El operador ? sigue el valor Result devuelto por File::open, pero esta función main tiene el tipo de retorno de (), no Result. Cuando compilamos este código, obtenemos el siguiente mensaje de error:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
  = help: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not implemented for `()`
help: consider adding return type
  |
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 |     let greeting_file = File::open("hello.txt")?;
5 +     Ok(())
  |

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` (bin "error-handling") due to 1 previous error

Este error señala que solo podemos usar el operador ? en una función que devuelve Result o Option o en cualquier otro tipo que implemente FromResidual.

Para corregir el error, tienes dos opciones. Una opción es cambiar el tipo de retorno de tu función para que sea compatible con el valor que estás usando el operador ? mientras no tengas restricciones que lo impidan. La otra opción es usar un match o uno de los métodos Result<T, E> para manejar el Result<T, E> de la manera que sea apropiada.

El mensaje de error también menciona que el operador ? también se puede usar con valores Option<T>. Al igual que con el uso de ? en Result, solo puedes usar ? en Option en una función que devuelve Option. El comportamiento del operador ? cuando se llama en un Option<T> es similar a su comportamiento cuando se llama en un Result<T, E>: si el valor es None, el None se devolverá temprano desde la función en ese punto. Si el valor es Some, el valor dentro de Some es el valor resultante de la expresión y la función continúa. El listado 9-11 tiene un ejemplo de una función que encuentra el último carácter de la primera línea en el texto dado:

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

Esta función devuelve Option<char> porque es posible que haya un carácter allí, pero también es posible que no lo haya. Este código toma el argumento de string slice text y llama al método lines en él, que devuelve un iterador sobre las líneas en el string. Debido a que esta función quiere examinar la primera línea, llama a next en el iterador para obtener el primer valor del iterador. Si text es un string vacío, esta llamada a next devolverá None, en cuyo caso usamos ? para detener y devolver None desde last_char_of_first_line. Si text no es un string vacío, next devolverá un valor Some que contiene un string slice de la primera línea en text.

El ? extrae el string slice, y podemos llamar a chars en ese string slice para obtener un iterador de sus caracteres. Estamos interesados en el último carácter en esta primera línea, por lo que llamamos a last para devolver el último elemento en el iterador. Esto es un Option porque es posible que la primera línea sea el string vacío, por ejemplo, si text comienza con una línea en blanco pero tiene caracteres en otras líneas, como en "\nhi". Sin embargo, si hay un último carácter en la primera línea, se devolverá en la variante Some. El operador ? en el medio nos da una forma concisa de expresar esta lógica, lo que nos permite implementar la función en una línea. Si no pudiéramos usar el operador ? en Option, tendríamos que implementar esta lógica usando más llamadas de método o una expresión match.

Ten en cuenta que puedes usar el operador ? en una función que devuelve Result y puedes usar el operador ? en una función que devuelve Option, pero no puedes mezclar y combinar. El operador ? no convertirá automáticamente un Result en un Option o viceversa; en esos casos, puedes usar métodos como el método ok en Result o el método ok_or en Option para hacer la conversión explícitamente.

Hasta ahora, todas las funciones main que hemos usado devuelven (). La función main es especial porque es el punto de entrada y salida de los programas ejecutables, y hay restricciones sobre cuál puede ser su tipo de retorno para que los programas se comporten como se espera.

Por suerte, main también puede devolver un Result<(), E>. El Listado 9-12 tiene el código del listado 9-10, pero hemos cambiado el tipo de retorno de main para que sea Result<(), Box<dyn Error>> y hemos agregado un valor de retorno Ok(()) al final. Este código ahora se compilará:

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

El Box<dyn Error> tipo es un trait object, que hablaremos en la sección “Usando Trait Objects que permiten valores de diferentes tipos” en el Capítulo 18. Por ahora, puedes leer Box<dyn Error> para significar “cualquier tipo de error”. Usar ? en un valor Result en una función main con el tipo de error Box<dyn Error> está permitido, porque permite que cualquier valor Err se devuelva temprano. A pesar de que el cuerpo de esta función main solo devolverá errores de tipo std::io::Error, al especificar Box<dyn Error>, esta firma seguirá siendo correcta incluso si se agrega más código que devuelva otros errores al cuerpo de main.

Cuando una función main devuelve un Result, el ejecutable puede salir con un valor de 0 si main devuelve Ok(()) y saldrá con un valor distinto de 0 si main devuelve un Err. Los ejecutables escritos en C devuelven enteros cuando salen: los programas que salen con éxito devuelven el entero 0, y los programas que devuelven un error devuelven algún entero distinto de 0. Rust también devuelve enteros de ejecutables para ser compatibles con esta convención.

La función main puede devolver cualquier tipo que implemente el trait std::process::Termination, que incluye una función report que devuelve un ExitCode. Consulta la documentación de la biblioteca estándar para obtener más información sobre la implementación del trait Termination para tus propios tipos.

Ahora que hemos discutido los detalles de llamar a panic! o devolver Result, volvamos al tema de cómo decidir cuál es apropiado usar en qué casos.

panic! o no panic!

Entonces, ¿cómo decides cuándo debes llamar a panic! y cuándo debes devolver Result? Cuando el código entra en panic, no hay forma de recuperarse. Podrías llamar a panic! para cualquier situación de error, ya sea que haya una forma posible de recuperarse o no, pero entonces estás tomando la decisión de que una situación es irreparable en nombre del código que llama. Cuando eliges devolver un valor Result, le das al código que llama opciones. El código que llama podría elegir intentar recuperarse de una manera que sea apropiada para su situación, o podría decidir que un valor Err en este caso es irreparable, por lo que puede llamar a panic! y convertir su error recuperable en uno irreparable. Por lo tanto, devolver Result es una buena opción predeterminada cuando estás definiendo una función que podría fallar.

En situaciones como ejemplos, código de prototipo y pruebas, es más apropiado escribir código que entre en panic en lugar de devolver un Result. Veamos por qué, luego discutiremos situaciones en las que el compilador no puede darse cuenta de que la falla es imposible, pero tú como humano puedes. El capítulo concluirá con algunas pautas generales sobre cómo decidir si entrar en panic en el código de la biblioteca.

Ejemplos, código de prototipo y test

Cuando estás escribiendo un ejemplo para ilustrar algún concepto, también incluir código de manejo de errores robusto puede hacer que el ejemplo sea menos claro. En los ejemplos, se entiende que una llamada a un método como unwrap que podría entrar en panic se entiende como un marcador de posición para la forma en que desea que su aplicación maneje los errores, que puede diferir según lo que el resto de su código está haciendo.

De manera similar, los métodos unwrap y expect son muy útiles cuando se prototipa, antes de que estés listo para decidir cómo manejar los errores. Dejan marcadores claros en tu código para cuando estés listo para hacer que tu programa sea más robusto.

Si una llamada a un método falla en una prueba, querrás que toda la prueba falle, incluso si ese método no es la funcionalidad en prueba. Debido a que panic! es la forma en que una prueba se marca como fallida, llamar a unwrap o expect es exactamente lo que debería suceder.

Casos en los que tienes mas informacion que el compilador

También sería apropiado llamar a unwrap o expect cuando tienes alguna otra lógica que garantiza que el Result tendrá un valor Ok, pero la lógica no es algo que el compilador entiende. Aún tendrás un valor Result que debes manejar: la operación que estás llamando aún tiene la posibilidad de fallar en general, incluso si es lógicamente imposible en tu situación particular. Si puedes asegurar inspeccionando manualmente el código que nunca tendrás una variante Err, es perfectamente aceptable llamar a unwrap, e incluso mejor documentar la razón por la que crees que nunca tendrás una variante Err en el texto de expect. Aquí hay un ejemplo:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

Aquí estamos creando una instancia IpAddr analizando una cadena codificada. Podemos ver que 127.0.0.1 es una dirección IP válida, por lo que es aceptable usar expect aquí. Sin embargo, tener una cadena válida codificada no cambia el tipo de retorno del método parse: aún obtenemos un valor Result, y el compilador aún nos hará manejar el Result como si la variante Err fuera una posibilidad porque el compilador no es lo suficientemente inteligente como para ver que esta cadena es siempre una dirección IP válida. Si la cadena de dirección IP proviniera de un usuario en lugar de estar codificada en el programa y, por lo tanto, tuviera una posibilidad de falla, definitivamente querríamos manejar el Result de una manera más robusta en su lugar. Mencionar la suposición de que esta dirección IP está codificada nos indicará que cambiemos expect a un mejor código de manejo de errores si en el futuro necesitamos obtener la dirección IP de otra fuente.

Pautas para el manejo de errores

Es aconsejable que tu código entre en panic cuando sea posible que tu código termine en un estado incorrecto. En este contexto, un estado incorrecto es cuando se ha roto alguna suposición, garantía, contrato o invariante, como cuando se pasan valores no válidos, valores contradictorios o valores faltantes a tu código, más uno o más de los siguientes:

• El mal estado es algo inesperado, a diferencia de algo que probablemente suceda ocasionalmente, como un usuario que ingresa datos en el formato incorrecto.
• Tu código después de este punto debe confiar en no estar en este mal estado, en lugar de verificar el problema en cada paso.
• No hay una buena manera de codificar esta información en los tipos que usas. Trabajaremos a través de un ejemplo de lo que queremos decir en la sección “Codificación de estados y comportamientos como tipos” del Capítulo 18.

Si alguien llama a tu código y pasa valores que no tienen sentido, es mejor devolver un error si puedes para que el usuario de la biblioteca pueda decidir qué hacer en ese caso. Sin embargo, en los casos en que continuar podría ser inseguro o dañino, la mejor opción podría ser llamar a panic! y alertar a la persona que usa tu biblioteca sobre el error en su código para que puedan solucionarlo durante el desarrollo. De manera similar, panic! a menudo es apropiado si estás llamando a un código externo que está fuera de tu control y devuelve un estado no válido que no tienes forma de solucionar.

Sin embargo, cuando se espera que falle, es más apropiado devolver un Result que hacer una llamada a panic!. Los ejemplos incluyen un analizador que recibe datos con formato incorrecto o una solicitud HTTP que devuelve un estado que indica que has alcanzado un límite de velocidad. En estos casos, devolver un Result indica que el fallo es una posibilidad esperada que el código llamado decidida cómo manejarlo.

Cuando tu código realiza una operación que podría poner a un usuario en riesgo si se llama con valores no válidos, tu código debe verificar primero que los valores sean válidos y entrar en panic si los valores no son válidos. Esto es principalmente por razones de seguridad: intentar operar con datos no válidos puede exponer tu código a vulnerabilidades. Esta es la razón principal por la que la biblioteca estándar llamará a panic! si intentas un acceso a memoria fuera de los límites: intentar acceder a la memoria que no pertenece a la estructura de datos actual es un problema de seguridad común. Las funciones suelen tener contratos: su comportamiento solo está garantizado si las entradas cumplen con requisitos particulares. Entrar en panic cuando se viola el contrato tiene sentido porque una violación del contrato siempre indica un error del lado del llamador y no es un tipo de error que deseas que el código llamado tenga que manejar explícitamente. De hecho, no hay una manera razonable para que el código de llamada se recupere; los programadores que llaman deben corregir el código. Los contratos para una función, especialmente cuando una violación causará un panic, deben explicarse en la documentación de la API de la función.

Sin embargo, tener muchas comprobaciones de errores en todas tus funciones sería verboso y molesto. Afortunadamente, puedes usar el sistema de tipos de Rust (y, por lo tanto, la comprobación de tipos realizada por el compilador) para hacer muchas de las comprobaciones por ti. Si tu función tiene un tipo particular como parámetro, puedes proceder con la lógica de tu código sabiendo que el compilador ya se ha asegurado de que tengas un valor válido. Por ejemplo, si tienes un tipo en lugar de un Option, tu programa espera tener algo en lugar de nada. Tu código entonces no tiene que manejar dos casos para las variantes Some y None: solo tendrá un caso para tener definitivamente un valor. El código que intenta pasar nada a tu función ni siquiera se compilará, por lo que tu función no tiene que verificar ese caso en tiempo de ejecución. Otro ejemplo es usar un tipo de entero sin signo como u32, que garantiza que el parámetro nunca sea negativo.

Creacion de tipos personalizados para validacion

Tomemos la idea de usar el sistema de tipos de Rust para garantizar que tengamos un valor válido un paso más allá y veamos cómo crear un tipo personalizado para validación. Recuerda el juego de adivinanzas en el Capítulo 2 en el que nuestro código le pidió al usuario que adivinara un número entre 1 y 100. Nunca validamos que la suposición del usuario estuviera entre esos números antes de verificarla con nuestro número secreto; solo validamos que la suposición fuera positiva. En este caso, las consecuencias no fueron muy graves: nuestra salida de “Demasiado alto” o “Demasiado bajo” seguiría siendo correcta. Pero sería una mejora útil guiar al usuario hacia suposiciones válidas y tener un comportamiento diferente cuando un usuario adivina un número que está fuera del rango en comparación con cuando un usuario escribe, por ejemplo, letras en su lugar.

Una forma de hacer esto sería analizar la suposición como un i32 en lugar de solo un u32 para permitir números potencialmente negativos, y luego agregar una verificación de que el número esté en el rango, de esta manera:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        // --snip--

        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: i32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --snip--
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

La expresión if verifica si nuestro valor está fuera del rango, le dice al usuario sobre el problema y llama a continue para iniciar la siguiente iteración del ciclo y pedir otra suposición. Después de la expresión if, podemos continuar con las comparaciones entre guess y el número secreto sabiendo que guess está entre 1 y 100.

Sin embargo, esta no es una solución ideal: si fuera absolutamente crítico que el programa solo operara en valores entre 1 y 100, y tuviera muchas funciones con este requisito, tener una verificación como esa en cada función sería tedioso (y podría afectar el rendimiento).

En su lugar, podemos crear un nuevo tipo y poner las verificaciones en una función para crear una instancia del tipo en lugar de repetir las verificaciones en cada función. De esa manera, es seguro que las funciones utilicen el nuevo tipo en sus firmas y utilicen los valores que reciben con confianza. El Listado 9-13 muestra una forma de definir un tipo Guess que solo creará una instancia de Guess si la función new recibe un valor entre 1 y 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

Primero, definimos un struct llamado Guess que tiene un campo llamado value que contiene un i32. Aquí es donde se almacenará el número.

Luego implementamos una función asociada llamada new en Guess que crea instancias de valores Guess. La función new está definida para tener un parámetro llamado value de tipo i32 y para devolver un Guess. El código en el cuerpo de la función new prueba value para asegurarse de que esté entre 1 y 100. Si value no pasa esta prueba, hacemos una llamada panic!, que alertará al programador que está escribiendo el código de llamada que tiene un error que debe corregir, porque crear un Guess con un value fuera de este rango violaría el contrato en el que Guess::new se basa. Las condiciones en las que Guess::new podría entrar en pánico deben discutirse en la documentación de la API de cara al público; cubriremos las convenciones de documentación que indican la posibilidad de un panic! en la documentación de la API que creas en el Capítulo 14. Si value pasa la prueba, creamos un nuevo Guess con su campo value establecido en el value y devolvemos el Guess.

A continuación, implementamos un método llamado value que toma prestado self, no tiene otros parámetros y devuelve un i32. Este tipo de método se llama a veces getter, porque su propósito es obtener algunos datos de sus campos y devolverlos. Este método público es necesario porque el campo value del struct Guess es privado. Es importante que el campo value sea privado para que el código que usa el struct Guess no pueda establecer value directamente: el código fuera del módulo debe usar la función Guess::new para crear una instancia de Guess, lo que garantiza que no hay forma de que un Guess tenga un value que no haya sido verificado por las condiciones en la función Guess::new.

Una función que tiene un parámetro o devuelve solo números entre 1 y 100 podría entonces declarar en su firma que toma o devuelve un Guess en lugar de un i32 y no necesitaría hacer ninguna verificación adicional en su cuerpo.

Resumen

Las características de manejo de errores de Rust están diseñadas para ayudarte a escribir un código más robusto. La macro panic! indica que tu programa está en un estado que no puede manejar y te permite indicarle al proceso que se detenga en lugar de intentar continuar con valores no válidos o incorrectos. El enum Result usa el sistema de tipos de Rust para indicar que las operaciones pueden fallar de una manera que tu código podría recuperar. Puedes usar Result para decirle al código que llama a tu código que necesita manejar el éxito o el error de manera potencial. Usar panic! y Result en las situaciones apropiadas hará que tu código sea más confiable ante los problemas inevitables.

Ahora que has visto formas útiles en que la biblioteca estándar usa generics con los enums Option y Result, hablaremos sobre cómo funcionan los generics y cómo puedes usarlos en tu código.

Tipos Genéricos, Traits y Lifetimes

Cada lenguaje de programación tiene herramientas para manejar eficazmente la duplicación de conceptos. En Rust, una de esas herramientas son los genéricos: sustitutos abstractos de tipos concretos u otras propiedades. Podemos expresar el comportamiento de los genéricos o cómo se relacionan con otros genéricos sin saber qué estará en su lugar cuando se compile y ejecute el código.

Las funciones pueden tomar parámetros de algún tipo genérico, en lugar de un tipo concreto como i32 o String, de la misma manera que una función toma parámetros con valores desconocidos para ejecutar el mismo código en múltiples valores concretos. De hecho, ya hemos usado genéricos en el Capítulo 6 con Option<T>, Capítulo 8 con Vec<T> y HashMap<K, V>, y Capítulo 9 con Result<T, E>. ¡En este capítulo, explorará cómo definir sus propios tipos, funciones y métodos con genéricos!

Primero, revisaremos cómo extraer una función para reducir la duplicación de código. Luego usaremos la misma técnica para hacer una función genérico a partir de dos funciones que difieren solo en los tipos de sus parámetros. También explicaremos cómo usar tipos genéricos en definiciones de structs y enums.

Entonces aprenderás cómo usar traits para definir el comportamiento de una manera genérica. Puedes combinar traits con tipos genéricos para restringir un tipo genérico para que acepte solo aquellos tipos que tienen un comportamiento particular, en lugar de cualquier tipo.

Finalmente, discutiremos lifetimes: una variedad de genéricos que le dan al compilador información sobre cómo se relacionan las referencias entre sí. Lifetimes nos permiten darle al compilador suficiente información sobre los valores prestados para que pueda garantizar que las referencias serán válidas en más situaciones de las que podría sin nuestra ayuda.

Eliminando la duplicación extrayendo una función

Los genéricos nos permiten reemplazar tipos específicos con un marcador de posición que representa múltiples tipos para eliminar la duplicación de código. Antes de sumergirnos en la sintaxis de los genéricos, veamos primero cómo eliminar la duplicación de código de una manera que no involucre tipos genéricos extrayendo una función que reemplace valores específicos con un marcador de posición que represente múltiples valores. ¡Luego aplicaremos la misma técnica para extraer una función genérica! Al observar cómo reconocer el código duplicado que puede usar en una función, comenzará a reconocer el código duplicado que puede usar en los genéricos.

Comenzamos con un corto programa en el listado 10-1 que encuentra el número más grande en una lista.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
    assert_eq!(*largest, 100);
}

Almacenamos una lista de enteros en la variable number_list y colocamos una referencia al primer número de la lista en una variable llamada largest. Luego iteramos a través de todos los números de la lista, y si el número actual es mayor que el número almacenado en largest, reemplazamos la referencia en esa variable. Sin embargo, si el número actual es menor o igual al número más grande visto hasta ahora, la variable no cambia, y el código pasa al siguiente número de la lista. Después de considerar todos los números de la lista, largest debería hacer referencia al número más grande, que en este caso es 100.

Ahora se nos ha encargado encontrar el número más grande en dos listas de números. Para hacerlo, podemos duplicar el código en el listado 10-1 y usar la misma lógica en dos lugares diferentes en el programa, como se muestra en el listado 10-2.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
}

Aunque este código funciona, duplicar el código es tedioso y propenso a errores. También tenemos que recordar actualizar el código en varios lugares cuando queremos cambiarlo.

Para eliminar esta duplicación, crearemos una abstracción definiendo una función que opera en cualquier lista de enteros que se pase en un parámetro. Esta solución hace que nuestro código sea más claro y nos permite expresar el concepto de encontrar el número más grande en una lista de forma abstracta.

En el listado 10-3, extraemos el código que encuentra el mayor número en una función llamada largest. Luego llamamos a la función para encontrar el mayor número en las dos listas del listado 10-2. También podríamos usar la función en cualquier otra lista de valores i32 que podríamos tener en el futuro.

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 6000);
}

La función largest tiene un parámetro llamado list, que representa cualquier slice de valores ì32 que podríamos pasar a la función. Como resultado, cuando llamamos a la función, el código se ejecuta en los valores específicos que pasamos.

En resumen, estos son los pasos que tomamos para cambiar el código del listado 10-2 al listado 10-3:

1. Identificar código duplicado.
2. Extraer el código duplicado en el cuerpo de la función y especificar las entradas y salidas de ese código en la firma de la función.
3. Actualizar las dos instancias de código duplicado para llamar a la función en su lugar.

A continuación, usaremos estos mismos pasos con los genéricos para reducir la duplicación de código. De la misma manera que el cuerpo de la función puede operar en una list abstracta en lugar de valores específicos, los genéricos permiten que el código opere en tipos abstractos.

Por ejemplo, digamos que teníamos dos funciones: una que encuentra el mayor elemento en un slices de valores i32 y otra que encuentra el mayor elemento en un slice de valores char. ¿Cómo eliminaríamos esa duplicación? ¡Averigüémoslo!

Tipos de Datos Genéricos

Utilizamos genéricos para crear definiciones para elementos como firmas de funciones o structs, que luego podemos usar con muchos tipos de datos concretos diferentes. Primero veamos cómo definir funciones, structs, enums y métodos usando genéricos. Luego discutiremos cómo los genéricos afectan el rendimiento del código.

Definiciones En Function

Al definir una función que usa genéricos, colocamos los genéricos en la firma de la función donde normalmente especificaríamos los tipos de datos de los parámetros y el valor de retorno. Hacerlo hace que nuestro código sea más flexible y brinda más funcionalidad a los llamadores de nuestra función al tiempo que evita la duplicación de código.

Continuando con nuestra función largest, el listado 10-4 muestra dos funciones que encuentran el valor más grande en un slice. Luego combinaremos estos en una sola función que usa genéricos.

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
    assert_eq!(*result, 'y');
}

La función largest_i32 es la que extrajimos en el listado 10-3 que encuentra el i32 más grande en un slice. La función largest_char encuentra el char más grande en un slice. Los cuerpos de las funciones tienen el mismo código, así que eliminemos la duplicación introduciendo un parámetro de tipo generic en una sola función.

Para parametrizar los tipos en una nueva función única, necesitamos nombrar el parámetro de tipo, tal como lo hacemos para los parámetros de valor de una función. Pero usaremos T porque, por convención, los nombres de los parámetros de tipo en Rust son cortos, a menudo solo una letra, y la convención de nomenclatura de tipo de Rust es UpperCamelCase. Abreviatura de "tipo", T es la opción predeterminada de la mayoría de los programadores de Rust.

Cuando usamos un parámetro en el cuerpo de la función, tenemos que declarar el nombre del parámetro en la firma para que el compilador sepa qué significa ese nombre. De manera similar, cuando usamos un nombre de parámetro de tipo en la firma de una función, tenemos que declarar el nombre del parámetro de tipo antes de usarlo. Para definir un genérico en la función largest, coloque las declaraciones de nombre de tipo dentro de corchetes angulares, <>, entre el nombre de la función y la lista de parámetros, así:

fn largest<T>(list: &[T]) -> &T {

Leemos esta definición como: la función largest es genérico sobre algún tipo T. Esta función tiene un parámetro llamado list, que es un slice de valores de tipo T. La función largest devolverá una referencia a un valor del mismo tipo T.

El listado 10-5 muestra la definición de la función largest combinada usando el tipo de datos genéricos en su firma. La lista también muestra cómo podemos llamar a la función con un slice de valores i32 o valores char. Tenga en cuenta que este código aún no se compilará, pero lo arreglaremos más adelante en este capítulo.

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

Si compilamos este código ahora, obtendremos este error:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

For more information about this error, try `rustc --explain E0369`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

El texto de ayuda menciona std::cmp::PartialOrd, que es un trait, y vamos a hablar de traits en la siguiente sección. Por ahora, sepa que este error indica que el cuerpo de largest no funcionará para todos los tipos posibles que podría ser T. Debido a que queremos comparar valores de tipo T en el cuerpo, solo podemos usar tipos cuyos valores se pueden ordenar. Para habilitar las comparaciones, la biblioteca estándar tiene el trait std::cmp::PartialOrd que puede implementar en tipos (consulte el Apéndice C para obtener más información sobre este trait). Siguiendo la sugerencia del texto de ayuda, restringimos los tipos válidos para T solo a aquellos que implementan PartialOrd y este ejemplo se compilará, porque la biblioteca estándar implementa PartialOrd tanto en i32 como en char.

Definiciones En Struct

También podemos definir structs para usar tipos genéricos en uno o más campos usando la sintaxis <>. El listado 10-6 define un struct Point<T> para contener valores x e y de cualquier tipo T.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

La sintaxis para usar genéricos en las definiciones de structs es similar a la que se usa en las definiciones de funciones. Primero, declaramos el nombre del parámetro de tipo dentro de corchetes angulares, justo después del nombre del struct. Luego, usamos el tipo genérico en la definición del struct donde especificaríamos tipos de datos concretos.

Ten en cuenta que porque hemos usado un solo tipo genérico para definir Point<T>, esta definición dice que el struct Point<T> es genérico sobre algún tipo T, y los campos x e y son ambos ese mismo tipo, sea cual sea ese tipo. Si creamos una instancia de un Point<T> que tenga valores de diferentes tipos, como en el listado 10-7, nuestro código no se compilará.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

En este ejemplo, cuando asignamos el valor entero 5 a x, le decimos al compilador que el tipo genérico T será un entero para esta instancia de Point<T>. Luego, cuando especificamos 4.0 para y, que hemos definido para tener el mismo tipo que x, obtendremos un error de tipo incompatible como este:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

For more information about this error, try `rustc --explain E0308`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

Para definir un struct Point donde x e y son ambos genéricos pero podrían tener diferentes tipos, podemos usar múltiples parámetros de tipo genérico. Por ejemplo, en el listado 10-8, cambiamos la definición de Point para que sea generic sobre los tipos T y U donde x es de tipo T y y es de tipo U.

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

¡Ahora todas las instancias de Point que se muestran se permiten! Puede usar tantos parámetros de tipo genérico en una definición como desee, pero usar más de unos pocos hace que su código sea difícil de leer. Si encuentra que necesita muchos tipos genéricos en su código, podría indicar que su código necesita reestructurarse en piezas más pequeñas.

Definiciones En Enum

Como hicimos con structs, podemos definir enums para contener tipos genéricos en sus variantes. Echemos otro vistazo al enum Option<T> que la biblioteca estándar proporciona, que usamos en el Capítulo 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

Esta definición debería tener más sentido para ti ahora. Como puede ver, el enum Option<T> es genérico sobre el tipo T y tiene dos variantes: Some, que contiene un valor de tipo T, y None, que no contiene ningún valor. Al usar el enum Option<T>, podemos expresar el concepto abstracto de un valor opcional, y porque Option<T> es genérico, podemos usar esta abstracción sin importar el tipo del valor opcional.

Los enums también pueden usar múltiples tipos genéricos. La definición del enum Result que usamos en el Capítulo 9 es un ejemplo:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

El enum Result es un genérico en dos tipos, T y E. Tiene dos variantes: Ok, que contiene un valor de tipo T, y Err, que contiene un valor de tipo E. Esta definición es apropiada porque el significado de Result es que uno de estos dos tipos, T o E, será el tipo del valor que se devuelve cuando se produce un error o cuando se tiene éxito (devolviendo un valor de tipo T) o falla (devolviendo un valor de tipo E). De hecho, esta es la definición que usamos para abrir un archivo en el listado 9-3, donde T se llenó con el tipo std::fs::File cuando el archivo se abrió con éxito y E se llenó con el tipo std::io::Error cuando hubo problemas para abrir el archivo.

Cuando reconoces situaciones en tu código con múltiples definiciones de struct o enum que difieren solo en los tipos de los valores que contienen, puedes evitar la duplicación usando tipos genéricos en su lugar.

Definiciones En Method

Podemos implementar métodos en structs y enums y usar tipos genéricos en sus definiciones también. El listado 10-9 muestra el struct Point<T> que definimos en el listado 10-6 con un método llamado x implementado en él.

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Aquí, hemos definido un método llamado x en Point<T> que devuelve una referencia a la data en el campo x.

Ten en cuenta que tenemos que declarar T justo después de impl para que podamos usar T para especificar que estamos implementando métodos en el tipo Point<T>. Al declarar T como un tipo genérico después de impl, Rust puede identificar que el tipo en los corchetes angulares en Point es un tipo generic en lugar de un tipo concreto. Podríamos haber elegido un nombre diferente para este parámetro genérico que el parámetro genérico declarado en la definición del struct, pero usar el mismo nombre es convencional. Los métodos escritos dentro de un impl que declara el tipo genérico se definirán en cualquier instancia del tipo, sin importar qué tipo concreto termine sustituyendo al tipo genérico.

También podemos especificar restricciones en los tipos genéricos al definir métodos en el tipo. Por ejemplo, podríamos implementar métodos solo en instancias de Point<T> con un tipo f32 concreto en lugar de en instancias de Point<T> con cualquier tipo genérico. En el listado 10-10 usamos el tipo concreto f32, lo que significa que no declaramos ningún tipo después de impl.

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

Este código significa que el tipo Point<f32> tendrá un método distance_from_origin definido en él, y otros tipos de Point<T> que no sean de tipo f32 no tendrán este método definido. El método mide qué tan lejos está nuestro punto del punto en las coordenadas (0.0, 0.0) y usa operaciones matemáticas que solo están disponibles para tipos de punto flotante.

Los parámetros de tipo genérico en una definición de struct no siempre son los mismos que los que usas en las firmas de métodos de ese mismo struct. El listado 10-11 usa los tipos genéricos X1 e Y1 para el struct Point y X2 Y2 para la firma del método mixup para hacer el ejemplo más claro. El método crea una nueva instancia de Point con el valor x del self Point (de tipo X1) y el valor y del Point pasado (de tipo Y2).

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

En main, hemos definido un Point que tiene un i32 para x (con valor 5) y un f64 para y (con valor 10.4). La variable p2 es un Point struct que tiene un string slice para x (con valor "Hello") y un char para y (con valor c). Llamar a mixup en p1 con el argumento p2 nos da p3, que tendrá un i32 para x, porque x vino de p1. La variable p3 tendrá un char para y, porque y vino de p2. La llamada al macro println! imprimirá p3.x = 5, p3.y = c.

El propósito de este ejemplo es demostrar una situación en la que algunos parámetros genérico se declaran con impl y otros se declaran con la definición del método. Aquí, los parámetros genérico X1 e Y1 se declaran después de impl porque van con la definición del struct. Los parámetros genérico X2 e Y2 se declaran después de fn mixup, porque solo son relevantes para el método.

Rendimiento de código usando genéricos

Quizás te estés preguntando si hay un costo de rendimiento al usar parámetros de tipo genérico. La buena noticia es que usar tipos genéricos no hará que tu programa se ejecute más lento de lo que lo haría con tipos concretos.

Rust logra esto realizando monomorfización del código usando genéricos en tiempo de compilación. Monomorfización es el proceso de convertir código genérico en código específico llenando los tipos concretos que se usan cuando se compila. En este proceso, el compilador hace lo contrario de los pasos que usamos para crear la función genérica en el listado 10-5: el compilador mira todos los lugares donde se llama el código genérico y genera código para los tipos concretos con los que se llama el código genérico.

Veamos como funciona esto usando el enum genérico de la biblioteca estándar Option<T>:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

Cuando Rust compila este código, realiza monomorfización. Durante ese proceso, el compilador lee los valores que se han usado en las instancias de Option<T> e identifica dos tipos de Option<T>: uno es i32 y el otro es f64. Como tal, expande la definición genérica de Option<T> en dos definiciones especializadas a i32 y f64, reemplazando así la definición genérica con las específicas.

La versión monomorfizada del código se ve similar al siguiente (el compilador usa nombres diferentes a los que estamos usando aquí para ilustración):

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

El genérico Option<T> se reemplaza con las definiciones específicas creadas por el compilador. Debido a que Rust compila código genérico en código que especifica el tipo en cada instancia, no pagamos ningún costo de rendimiento por usar genéricos. Cuando el código se ejecuta, se comporta de la misma manera que si hubiéramos duplicado cada definición a mano. El proceso de monomorfización hace que los genéricos de Rust sean extremadamente eficientes en tiempo de ejecución.

Traits: Definiendo Comportamiento Compartido

Un trait define funcionalidad que un tipo particular tiene y puede compartir con otros tipos. Podemos usar traits para definir comportamiento compartido de una manera abstracta. Podemos usar trait bounds para especificar que un tipo genérico puede ser cualquier tipo que tenga cierto comportamiento.

Nota: Los traits son similares a una característica a menudo llamada interfaces en otros lenguajes, aunque con algunas diferencias. En español también se les conoce como rasgos pero en el libro intentaremos mantener la palabra clave sin traducir, no obstante creamos esta encuesta para futuras revisiones.

Definiendo un Trait

El comportamiento de un tipo consiste en los métodos que podemos llamar en ese tipo. Diferentes tipos comparten el mismo comportamiento si podemos llamar los mismos métodos en todos esos tipos. Las definiciones de traits son una manera de agrupar firmas de métodos para definir un conjunto de comportamientos necesarios para lograr algún propósito.

Por ejemplo, digamos que tenemos múltiples structs que contienen varios tipos y cantidades de texto: un struct NewsArticle que contiene una historia de noticias archivada en una ubicación particular y un Tweet que puede tener como máximo 280 caracteres junto con metadatos que indican si es un nuevo tweet, un retweet, o una respuesta a otro tweet.

Queremos hacer una biblioteca de agregación de medios llamada aggregator que puede mostrar resúmenes de datos que podrían estar almacenados en una instancia de NewsArticle o Tweet. Para hacer esto, necesitamos un resumen de cada tipo, y solicitaremos ese resumen llamando un método summarize en una instancia. El listado 10-12 muestra la definición de un trait Summary público que expresa este comportamiento.

pub trait Summary {
    fn summarize(&self) -> String;
}

Aquí, declaramos un trait usando la palabra clave trait y luego el nombre del trait, que en este caso es Summary. También hemos declarado el trait como pub para que los crates que dependen de este crate puedan hacer uso de este trait también, como veremos en algunos ejemplos. Dentro de las llaves curvas, declaramos las firmas de los métodos que describen los comportamientos de los tipos que implementan este trait, que en este caso es fn summarize (&self) -> String.

Después de la firma del método, en lugar de proporcionar una implementación dentro de llaves curvas, usamos un punto y coma. Cada tipo que implementa este trait debe proporcionar su propio comportamiento personalizado para el cuerpo del método. El compilador hará cumplir que cualquier tipo que tenga el trait Summary tendrá el método summarize definido con esta firma exactamente.

Un trait puede tener múltiples métodos en su cuerpo: las firmas de los métodos se enumeran una por línea y cada línea termina en un punto y coma.

Implementando un Trait en un Tipo

Ahora que hemos definido el trait Summary, podemos implementarlo en los tipos en nuestro agregador de medios. El listado 10-13 muestra una implementación del trait Summary en el struct NewsArticle que usa el encabezado, el autor y la ubicación para crear el valor de retorno de summarize. Para el struct Tweet, definimos summarize como el nombre de usuario seguido del texto completo del tweet, asumiendo que el contenido del tweet ya está limitado a 280 caracteres.

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Implementar un trait en un tipo es similar a implementar métodos regulares. La diferencia es que después de impl, ponemos el nombre del trait que queremos implementar, luego usamos la palabra clave for, y luego especificamos el nombre del tipo que queremos implementar el trait. Dentro del bloque impl, ponemos las firmas de los métodos que la definición del trait ha definido. En lugar de agregar un punto y coma después de cada firma, usamos llaves y llenamos el cuerpo del método con el comportamiento específico que queremos que los métodos del trait tengan para el tipo en particular.

Ahora que la biblioteca ha implementado el trait Summary en NewsArticle y Tweet, los usuarios de la biblioteca pueden llamar a los métodos de trait en las instancias de NewsArticle y Tweet en la misma forma en que llamamos a los métodos regulares. La única diferencia es que el usuario debe traer el trait al scope, así como los tipos. Aquí hay un ejemplo de cómo un crate binario podría usar nuestra biblioteca de aggregator:

use aggregator::{Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 new tweet: {}", tweet.summarize());
}

Este código imprime New article available! horse_ebooks: of course, as you probably already know, people.

Otros crates que dependen de nuestro crate aggregator pueden usar el trait Summary en el ámbito para implementar Summary en sus propios tipos. Una restricción a tener en cuenta es que podemos implementar un trait en un tipo solo si ambos el trait o el tipo, o ambos, son local a nuestro crate. Por ejemplo, podemos implementar traits de la biblioteca estándar como Display en un tipo personalizado como Tweet como parte de nuestra funcionalidad de crate aggregator, porque el tipo Tweet es local a nuestro crate aggregator. También podemos implementar Summary en Vec<T> en nuestro crate aggregator, porque el trait Summary es local a nuestro crate aggregator.

Pero no podemos implementar traits externos en tipos externos. Por ejemplo, digamos que queremos implementar Display en Vec<T> como parte de nuestra funcionalidad de crate aggregator. Esto no es posible porque tanto Display como Vec<T> están definidos en la biblioteca estándar y no son locales a nuestro crate aggregator. La restricción de implementar un trait en un tipo solo si uno de ellos es local a nuestro crate es parte de una propiedad llamada coherencia, y más específicamente la regla huérfana, así llamada porque el tipo padre no está presente. Esta regla asegura que el código de otras personas no pueda romper su código y viceversa. Sin la regla, dos crates podrían implementar el mismo trait para el mismo tipo, y Rust no sabría qué implementación usar.

Implementaciones predeterminadas

A veces es útil tener un comportamiento predeterminado para algunos o todos los métodos en un trait en lugar de requerir implementaciones para todos los métodos en cada tipo. Luego, a medida que implementamos el trait en un tipo particular, podemos mantener o anular el comportamiento predeterminado para cada método.

En el listado 10-14, especificamos un string predeterminado para el método summarize del trait Summary en lugar de solo definir la firma del método, como hicimos en el listado 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

Para usar una implementación predeterminada para resumir instancias de NewsArticle, especificamos un bloque impl vacío con impl Summary for NewsArticle {}.

Aunque ya no estamos definiendo el método summarize en NewsArticle directamente, hemos proporcionado una implementación predeterminada y especificado que NewsArticle implementa el trait Summary. Como resultado, todavía podemos llamar al método summarize en una instancia de NewsArticle, como esto:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

Este código imprime New article available! (Read more...).

Crear una implementación predeterminada no requiere que cambiemos nada sobre la implementación de Summary en Tweet en el listado 10-13. La razón es que la sintaxis para anular una implementación predeterminada es la misma que la sintaxis para implementar un método de trait que no tiene una implementación predeterminada.

Las implementaciones predeterminadas pueden llamar otros métodos en el mismo trait, incluso si esos métodos no tienen una implementación predeterminada. De esta manera, un trait puede proporcionar una gran cantidad de funcionalidad útil y solo requiere que los implementadores especifiquen una pequeña parte de ella. Por ejemplo, podríamos definir el trait Summary para tener un método summarize_author cuya implementación es requerida, y luego definir un método summarize que tenga una implementación predeterminada que llame al método summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Para usar esta version de Summary, solo necesitamos definir summarize_author cuando implementamos el trait en un tipo:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

Después de definir summarize_author, podemos llamar a summarize en instancias de la estructura Tweet, y la implementación predeterminada de summarize llamará a la definición de summarize_author que hemos proporcionado. Debido a que hemos implementado summarize_author, el trait Summary nos ha dado el comportamiento del método summarize sin requerirnos escribir más código.

use aggregator::{self, Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 new tweet: {}", tweet.summarize());
}

Este código imprime 1 new tweet: (Read more from @horse_ebooks...).

Ten en cuenta que no es posible llamar a la implementación predeterminada desde una implementación primordial de ese mismo método.

Traits como parametros

Ahora que sabes cómo definir y implementar traits, podemos explorar cómo usar traits para definir funciones que aceptan muchos tipos diferentes. Usaremos el trait Summary que implementamos en los tipos NewsArticle y Tweet en el listado 10-13 para definir una función notify que llama al método summarize en su parámetro item, que es de algún tipo que implementa el trait Summary. Para hacer esto, usamos la sintaxis impl Trait, como esto:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

En lugar de un tipo concreto para el parámetro item, especificamos el parámetro impl y el nombre del trait. Cualquier tipo que implemente el trait Summary puede ser pasado al parámetro item en la función notify. El código que llama a la función notify con cualquier otro tipo, como un String o un i32, no compilará porque esos tipos no implementan Summary.

Sintaxis de trait bound

La sintaxis impl Trait funciona para casos sencillos, pero en realidad es azúcar sintáctico para una forma más larga conocida como trait bound; se ve así:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

Esta forma más larga es equivalente al ejemplo en la sección anterior pero más detallado. Colocamos los límites de los traits con la declaración del parámetro generic después de dos puntos y dentro de corchetes angulares.

La sintaxis impl Trait es conveniente y hace que el código sea más conciso en casos simples, mientras que la sintaxis de trait bound más completa puede expresar más complejidad en otros casos. Por ejemplo, podemos tener dos parámetros que implementan Summary. Hacerlo con la sintaxis impl Trait se ve así:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

Usando impl Trait es apropiado si queremos que esta función permita que item1 y item2 tengan tipos diferentes (siempre que ambos tipos implementen Summary). Sin embargo, si queremos forzar que ambos parámetros tengan el mismo tipo, debemos usar un trait bound, como esto:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

El tipo generic T especificado como el tipo de los parámetros item1 e item2 restringe la función de tal manera que el tipo concreto del valor pasado como argumento para item1 e item2 debe ser el mismo.

Especificando múltiples trait bounds con la sintaxis +

También podemos especificar más de un trait bound. Digamos que queremos que notify use la representación de cadena de un tipo que implementa Summary en el cuerpo de la función. Para hacer esto, necesitamos que el parámetro item implemente tanto Display como Summary. Podemos hacerlo usando la sintaxis +:

pub fn notify(item: &(impl Summary + Display)) {

La sintaxis + también es válida con los trait bounds en tipos generics:

pub fn notify<T: Summary + Display>(item: &T) {

Con los dos trait bounds especificados, el cuerpo de notify puede llamar a summarize y usar {} para formatear item.

Trait bounds más claros con cláusulas where

Usar demasiados trait bounds tiene sus inconvenientes. Cada generic tiene sus propios trait bounds, por lo que las funciones con múltiples parámetros de tipo generic pueden contener mucha información de trait bound entre el nombre de la función y su lista de parámetros, lo que hace que la firma de la función sea difícil de leer. Por esta razón, Rust tiene una sintaxis alternativa para especificar los trait bounds dentro de una cláusula where después de la firma de la función. Así que en lugar de escribir esto:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

podemos usar una cláusula where, como esta:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

La firma de esta función está menos desordenada: el nombre de la función, la lista de parámetros y el tipo de retorno están muy juntos, similar a una función sin muchos trait bounds.

Devolviendo tipos que implementan traits

También podemos usar la sintaxis impl Trait en el tipo de retorno de una función para devolver un valor de algún tipo que implementa un trait, como se muestra aquí:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    }
}