Te damos la bienvenida a Comprehensive Rust 🦀

Este es un curso de Rust de tres días que ha desarrollado el equipo de Android de Google. El curso abarca todo lo relacionado con Rust, desde la sintaxis básica hasta temas avanzados como los genéricos y la gestión de errores. También incluye contenidos específicos de Android el último día.

La última versión del curso se puede encontrar en https://google.github.io/comprehensive-rust/. Si lo estás leyendo en otro lugar, consulta allí para obtener actualizaciones.

Este curso está disponible en otros idiomas. Seleccione su idioma preferido en la esquina superior a la derecha, o navega a la página de [Tradduciones](Translations](running-the-course/translations.md) para una lista de todas las traducciones disponibles.

Este curso tambien está disponible como un PDF.

El objetivo del curso es enseñarte Rust. Suponemos que no sabes nada sobre Rust y esperamos lograr lo siguiente:

• Darte un entendimiento comprensivo de la sintaxis y lenguaje Rust.
• Permitirte modificar programas de Rust y escribir otros nuevos.
• Enseñarte idiomática propia de Rust.

Llamamos a los cuatro primeros días del curso Fundamentos de Rust.

Basándonos en esto, te invitamos a profundizar en uno o más temas especializados:

• Android: un curso de medio día sobre el uso de Rust en el desarrollo de la plataforma Android (AOSP). En él se incluye la interoperabilidad con C, C++ y Java.
• Chromium: una clase de medio día sobre el uso de Rust dentro del navegador Chromium. Incluye interoperabilidad con C++ y como incorporar bibliotecas de tercer partido ("crates") en Chromium.
• Bare Metal: una clase de un día sobre el uso de Rust para el desarrollo bare-metal (insertado). Se tratarán tanto los microcontroladores como los procesadores de aplicaciones.
• Concurrencia: una clase de un día sobre concurrencia en Rust. Abordaremos tanto la concurrencia clásica (programación interrumpible mediante hilos y exclusiones mutuas), como la concurrencia async / await (multitarea cooperativa mediante traits future).

Objetivos que no trataremos

Rust es un lenguaje muy amplio y no podremos abarcarlo todo en unos pocos días. Algunos de los objetivos que no se plantean en este curso son los siguientes:

• Aprender a desarrollar macros: consulta el capítulo 19.5 del Libro de Rust y Rust by Example.

Suposiciones

El curso presupone que ya sabes programar. Rust es un lenguaje estáticamente tipado y, a veces, haremos comparaciones con C y C++ para explicarlo mejor o contrastar nuestro enfoque.

Si sabes programar en un lenguaje dinámicamente tipado, como Python o JavaScript, podrás seguir el ritmo sin problema.

Desarrollo del curso

Esta página está dirigida al instructor del curso.

A continuación, te ofrecemos información general sobre cómo se ha desarrollado el curso en Google.

Normalmente impartimos las clases de 09:00 a 16:00, con una pausa para almorzar de una hora. Esto deja 3 horas para la clase de la mañana y 3 horas para la clase de la tarde. Ambas sesiones incluyen varias pausas y tiempo para que los estudiantes completen los ejercicios.

Antes de impartir el curso, te recomdamos hacer lo siguiente:

1. Familiarízate con el material del curso. Hemos incluido notas del orador para destacar los puntos clave (ayúdanos a añadir más notas de este tipo). Cuando hagas una presentación, asegúrate de abrir las notas del orador en una ventana emergente (haz clic en el enlace que tiene una pequeña flecha junto a "Notas del orador"). De esta manera, tendrás una pantalla despejada para mostrar a la clase.

2. Decide bien las fechas. Dado que el curso dura cuatro días, te recomendamos que repartas los días a lo largo de dos semanas. Los participantes del curso han dicho que les resulta útil hacer pausas durante el curso, ya que les ayuda a procesar toda la información que les proporcionamos.

3. Busca una sala con capacidad suficiente para los participantes presenciales. Recomendamos una sala para entre 15 y 25 personas. Es el tamaño ideal para que los alumnos se sientan cómodos haciendo preguntas y para que el profesor tenga tiempo de responderlas. Asegúrate de que en la sala haya mesas para ti y para los alumnos: todos necesitaréis sentaros y trabajar con vuestros portátiles. Además, como instructor, programarás mucho en directo, por lo que un atril no te resultará muy útil.

4. El mismo día del curso, llega con antelación a la clase para preparar todo lo necesario. Te recomendamos que realices la presentación directamente desde mdbook serve en tu portátil (consulta las [instrucciones de instalación][3]). Así conseguirás un rendimiento óptimo y que no haya demoras al pasar de una página a otra. También podrás corregir las erratas a medida que tú o los participantes del curso las detectéis.

5. Deja que los alumnos resuelvan los ejercicios por sí mismos o en pequeños grupos. Solemos dedicar entre 30 y 45 minutos a los ejercicios por la mañana y por la tarde (incluido el tiempo para revisar las soluciones). Asegúrate de preguntar a los asistentes si les está costando hacerlo o si hay algo en lo que puedas ayudarles. Cuando veas que varias personas tienen el mismo problema, coméntalo delante de la clase y ofrece una solución. Por ejemplo, enséñales dónde encontrar la información importante en la biblioteca estándar.

Eso es todo. ¡Buena suerte con el curso, y esperamos que te diviertas tanto como nosotros!

Después, envíanos un comentario para que podamos seguir mejorando el curso. Estaremos encantados de que nos cuentes qué aspectos destacarías y qué se puede mejorar. Tus alumnos también pueden enviarnos sus sugerencias!

Estructura del curso

Esta página está dirigida al instructor del curso.

Fundamentos de Rust

Los primeros cuatro días forman los Fundamentos de Rust. ¡Los días son muy intensos y cubrimos mucho terreno!

Horario del curso:

• Día 1 por la mañana (2 horas y 5 minutos, incluidos los descansos)

• Día 1 por la tarde (2 horas y 35 minutos, incluidos los descansos)

• Día 2 por la mañana (2 horas y 10 minutos, incluidos los descansos)

• Día 2 por la tarde (3 horas y 15 minutos, incluidos los descansos)

• Día 3 por la mañana (2 horas y 20 minutos, incluidos los descansos)

• Día 3 por la tarde (1 hora y 55 minutos, incluidos los descansos)

• Día 4 por la mañana (2 horas y 40 minutos, incluidos los descansos)

• Día 4 por la tarde (2 horas y 15 minutos, incluidos los descansos)

Información más detallada

Además de la clase de 4 días sobre los fundamentos de Rust, abordamos algunos temas más especializados:

Rust en Android

Rust en Android es un curso de medio día sobre el uso de Rust para el desarrollo de la plataforma Android. En él se incluye la interoperabilidad con C, C++ y Java.

Necesitarás conseguir el AOSP. Descarga el repositorio del curso en el mismo ordenador y mueve el directorio src/android/ a la raíz del AOSP. De esta forma, el sistema de compilación de Android verá los archivos Android.bp en src/android/.

Asegúrate que adb sync funciona con tu emulador o en un dispositivo físico y haz pre-build en todos los ejemplos de Android usando src/android/build_all.sh. Lee el script para ver los comandos que corren y asegúrate que funcionan cuando lo corres a mano.

Rust en Chromium

Rust en Chromium es una clase en profundidad de medio día sobre el uso de Rust como parte del navegador Chromium. Incluye el uso de Rust en el sistema de compilación gn de Chromium e incorpora bibliotecas de terceros ("crates") e interoperabilidad en C++.

Deberás poder compilar Chromium: [recomendamos] una compilación de depuración de componentes (../chromium/setup.md) por cuestiones de velocidad, pero cualquier compilación funcionará de forma correcta. Asegúrate de que puedes ejecutar el navegador Chromium que has compilado.

Bare Metal Rust

Bare Metal Rust es una clase de un día sobre cómo usar Rust para el desarrollo bare-metal (insertado). Se tratarán tanto microcontroladores como procesadores de aplicaciones.

Para la parte de los microcontroladores, necesitarás comprar con antelación la segunda versión de la placa programable BBC micro:bit. Todo el mundo deberá instalar una serie de paquetes, tal como se describe en la página de bienvenida.

Concurrencia en Rust

Concurrencia en profundidad es una clase de un día sobre la concurrencia clásica y la concurrencia async/await.

Necesitarás configurar un nuevo crate, y descargar y preparar las dependencias. A continuación, podrás copiar y pegar los ejemplos en src/main.rs para experimentar con ellos:

cargo init concurrency
cd concurrency
cargo add tokio --features full
cargo run

Horario del curso:

• Mañana (3 horas y205 minutos, incluidos los descansos)

• Por la tarde (3 horas y 20 minutos, incluidos los descansos)

Formato

El curso está diseñado para ser muy interactivo, por lo que te recomendamos que dejes que las preguntas guíen el aprendizaje de Rust.

Combinaciones de teclas

Existen varias combinaciones de teclas útiles en mdBook:

• Arrow-Left: Navegar a la página anterior.
• Arrow-Right: Navegar a la siguiente página.
• Ctrl + Enter: Ejecutar el código de ejemplo seleccionado.
• s: Activar la barra de búsqueda.

Traducciones

El curso se ha traducido a otros idiomas gracias a grupo de maravillosos voluntarios:

• Portugués Brasileño por @rastringer, @hugojacob, @joaovicmendes y @henrif75.
• Chino (simplificado) por @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK y @nodmp.
• Chino (tradicional) por @hueich, @victorhsieh, @mingyc, @kuanhungchen y @johnathan79717.
• Japonés por @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi y @kantasv.
• Coreano por @keispace, @jiyongp, @jooyunghan, y @namhyung.
• Español por @deavid.
• Ucranio por @git-user-cpp, @yaremam, y @reta.

Cambia el idioma con el seleccionador situado en la esquina superior derecha.

Traducciones Incompletas

Hay muchas traducciones todavía en curso. A continuación, incluimos enlaces a las traducciones más actualizadas:

• Árabe por @younies
• Bengalí por @raselmandol.
• Francés por @KookaS, @vcaen, y @AdrienBaudemont.
• Alemán por @Throvn y @ronaldfw.
• Italiano por @henrythebuilder y @detro.

La lista completa de traducciones con su estado corriente también esta disponible a partir de su ultima actualización o sincronizado a la versión mas reciente del curso.

Si quieres ayudar en esta iniciativa, consulta nuestras instrucciones para empezar. Las traducciones se coordinan en la herramienta de seguimiento de incidencias.

Usando Cargo

Cuando empieces a informarte sobre Rust, conocerás Cargo, la herramienta estándar que se utiliza en el ecosistema de Rust para crear y ejecutar sus aplicaciones. En este artículo, te ofrecemos una breve descripción de lo que es Cargo, cómo se integra en el ecosistema más amplio y cómo encaja en esta formación.

Instalación

Sigue las instrucciones que se indican en https://rustup.rs/.

Esto te dará la herramienta de compilación Cargo (cargo) y el compilador Rust (rustc). También obtendrás rustup, una utilidad de línea de comandos que puedes utilizar para instalar diferentes versiones del compilador.

Después de instalar Rust, debes configurar tu editor o IDE para utilizar Rust. La mayoría de los editores lo hacen con rust-analyzer, que ofrece funciones de autocompletado y salto a la definición para VS Code, Emacs y Vim/Neovim, entre otros. También hay disponible otro IDE denominado RustRover.

El ecosistema de Rust

El ecosistema de Rust se compone de varias herramientas, entre las que se incluyen las siguientes:

• rustc: el compilador de Rust que convierte archivos .rs en binarios y otros formatos intermedios.

• cargo: herramienta de compilación y gestión de dependencias de Rust. Cargo sabe cómo descargar dependencias, que normalmente se alojan en https://crates.io, y las transfiere a rustc al crear el proyecto. Cargo también incorpora un ejecutor de pruebas que se utiliza para realizar pruebas unitarias.

• rustup: el instalador y actualizador de cadenas de herramientas de Rust. Esta herramienta se utiliza para instalar y actualizar rustc y cargo cuando se lanzan nuevas versiones de Rust. Además, rustup también puede descargar documentación de la biblioteca estándar. Puedes tener varias versiones de Rust instaladas a la vez y rustup te permitirá cambiar de una a otra según lo necesites.

Código de ejemplo en esta formación

En esta formación, aprenderemos el lenguaje Rust principalmente con ejemplos que podrás ejecutar con tu navegador. De este modo, la configuración es mucho más sencilla y se asegura una experiencia homogénea para todos.

Se recomienda instalar Cargo, ya que facilitará la realización de los ejercicios. El último día realizaremos un ejercicio más largo en el que se mostrará cómo trabajar con dependencias, y para eso se necesita Cargo.

Los bloques de código de este curso son totalmente interactivos:

fn main() {
    println!("¡Edítame!");
}

Puedes usar Ctrl + Enter para ejecutar el código cuando el cursor esté en el cuadro de texto.

Ejecutar código de forma local con Cargo

Si quieres experimentar con el código en tu propio sistema, primero tendrás que instalar Rust. Para ello, sigue las instrucciones del Libro de Rust. De este modo, obtendrás un rustc y un cargo que funcionen. En el momento de escribir esto, la última versión estable de Rust tiene estos números de versión:

% rustc --version
rustc 1.69.0 (84c898d65 2023-04-16)
% cargo --version
cargo 1.69.0 (6e9a83356 2023-04-12)

También puedes usar cualquier versión posterior, ya que Rust mantiene la retrocompatibilidad.

Una vez hecho lo anterior, sigue estos pasos para compilar un binario de Rust a partir de uno de los ejemplos de la formación:

1. Haz clic en el botón "Copiar en el portapapeles" del ejemplo que quieras copiar.

2. Usa cargo new exercise para crear un directorio exercise/ para tu código:

   $ cargo new exercise
        Created binary (application) `exercise` package
   

3. Ve a exercise/ y usa cargo run para compilar y ejecutar tu binario:

   $ cd exercise
   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.75s
        Running `target/debug/exercise`
   Hello, world!
   

4. Sustituye el código de plantilla en src/main.rs con tu propio código. Por ejemplo, usando el ejemplo de la página anterior, haz que src/main.rs tenga el siguiente aspecto:

   fn main() {
       println!("¡Edítame!");
   }

5. Usa cargo run para hacer build y ejecutar tu binario actualizado:

   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.24s
        Running `target/debug/exercise`
   Edit me!
   

6. Comprueba que no haya errores en el proyecto con cargo check. Compílalo sin ejecutarlo con cargo build. Encontrarás la salida en target/debug/ para una versión de depuración normal. Usa cargo build --release para generar una compilación de lanzamiento optimizada en target/release/.

7. Edita Cargo.toml para añadir dependencias a tu proyecto. Cuando ejecutes comandos cargo, se descargarán y compilarán automáticamente las dependencias que falten.

Te damos la bienvenida al Día 1

Este es el primer día de Comprehensive Rust. Hoy trataremos muchos temas:

• Sintaxis básica Rust: variables, scalar y tipos compuestos, enums, structs, references, funciones, y métodos.
• Inferencia de tipos.
• Construcciones de flujos de control: bucles, condicionales, etc.
• Tipos definidos por el usuario: estructuras y enumeraciones.
• Emparejamiento de Patrones: desestructuración de enums, structs y arrays.

Horario

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 5 minutos. Esta sesión contiene:

Hola, Mundo

Esta sección tiene una duración aproximada de 15 minutos y contiene:

¿Qué es Rust?

Rust es un nuevo lenguaje de programación que lanzó su versión 1.0 en el 2015:

• Rust es un lenguaje compilado estático similar a C++
  • rustc usa LLVM como backend.
• Rust es compatible con muchas plataformas y arquitecturas:
  • x86, ARM, WebAssembly, ...
  • Linux, Mac, Windows, ...
• Rust se utiliza en una gran variedad de dispositivos:
  • firmware y cargadores de inicio,
  • pantallas inteligentes,
  • teléfonos móviles,
  • ordenadores,
  • servidores.

Ventajas de Rust

Estas son algunas de las ventajas competitivas de Rust:

• Seguridad de la memoria durante el tiempo de compilación: se evitan clases completas de errores de memoria durante el tiempo de compilación

  • No hay variables no inicializadas.
  • No hay errores double free.
  • No hay errores use-after-free.
  • No hay punteros NULL.
  • No se olvidan las exclusiones mutuas bloqueadas.
  • No hay condiciones de carrera de datos entre hilos.
  • No se invalidan los iteradores.

• No hay comportamientos indefinidos en el tiempo de ejecución: es decir, una instrucción de Rust nunca queda sin especificar

  • Se comprueban los límites de acceso a los arrays.
  • Se define el desbordamiento de enteros (panic o wrap-around).

• Características de los lenguajes modernos: es tan expresivo y ergonómico como los lenguajes de nivel superior

  • Enumeraciones (Enums) y coincidencia de patrones.
  • Genéricos.
  • Sin overhead de FFI.
  • Abstracciones sin coste.
  • Excelentes errores de compilación.
  • Gestor de dependencias integrado.
  • Asistencia integrada para pruebas.
  • Compatibilidad excelente con el protocolo del servidor de lenguaje.

Playground

El playground de Rust ofrece una forma sencilla de ejecutar programas cortos de Rust y es la base de los ejemplos y ejercicios de este curso. Prueba a ejecutar el programa "hello-world" con el que empieza. Incluye algunas funciones útiles:

• En "Tools", usa la opción rustfmt para dar formato al código de forma "estándar".

• Rust cuenta con dos "perfiles" principales para generar código: Debug (comprobaciones adicionales del tiempo de ejecución, menor optimización) y Release (menos comprobaciones del tiempo de ejecución y mayor optimización). Puedes acceder a ellos haciendo clic en "Debug", en la parte superior.

• Si te interesa, utiliza la opción "ASM" en "..." para ver el código de ensamblado que se ha generado.

Tipos y valores

Esta sección tiene una duración aproximada de 40 minutos y contiene:

Hola, Mundo

Vamos a hablar del programa Rust más simple, un clásico Hola Mundo:

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

Lo que ves:

• Las funciones se introducen con fn.
• Los bloques se delimitan con llaves, como en C y C++.
• La función main es el punto de entrada del programa.
• Rust tiene macros higiénicas, como por ejemplo println!.
• Las cadenas de Rust están codificadas en UTF-8 y pueden contener caracteres Unicode.

Variables

Rust ofrece seguridad de tipos mediante tipado estático. Los enlaces a variables son hechos con let:

fn main() {
    let x: i32 = 10;
    println!("x: {x}");
    // x = 20;
    // println!("x: {x}");
}

Valores

A continuación, se muestran algunos tipos integrados básicos, así como la sintaxis de los valores literales de cada tipo.

Los tipos tienen la siguiente anchura:

• iN, uN, and fN son N bits de capacidad,
• isize y usize tienen el ancho de un puntero,
• char tiene un tamaño de 32 bits,
• bool tiene 8 bits de ancho.

Aritmética

fn interproduct(a: i32, b: i32, c: i32) -> i32 {
    return a * b + b * c + c * a;
}

fn main() {
    println!("resultado: {}", interproduct(120, 100, 248));
}

Inferencia de tipos

Rust consultará cómo se usa la variable para determinar el tipo:

fn takes_u32(x: u32) {
    println!("u32: {x}");
}

fn takes_i8(y: i8) {
    println!("i8: {y}");
}

fn main() {
    let x = 10;
    let y = 20;

    takes_u32(x);
    takes_i8(y);
    // takes_u32(y);
}

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ERROR: no hay implementación para `{float} == {integer}`
}

Ejercicio: Fibonacci

La secuencie de Fibonacci empieza con [0, 1]. Para n>1, el número de Fibonacci en la posición n se calcula de forma recursiva como la suma de los números de Fibonacci n-1 y n-2.

Escribe una función fib(n) que calcule el número n de Fibonacci. ¿Cuándo da error pánico esta función?

fn fib(n: u32) -> u32 {
    if n < 2 {
        // El caso base.
        todo!("Implementar esto")
    } else {
        // El caso recursivo.
        todo!("Implementar esto")
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

Solución

fn fib(n: u32) -> u32 {
    if n < 2 {
        return n;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

Básicos de Control de Flujo

Esta sección tiene una duración aproximada de 40 minutos y contiene:

Expresiones if

Puedes usar expresiones if de la misma forma que en otros lenguajes:

fn main() {
    let x = 10;
    if x == 0 {
        println!("cero!");
    } else if x < 100 {
        println!("muy grande");
    } else {
        println!("enorme");
    }
}

Además, puedes utilizar if como expresión. La última expresión de cada bloque se convierte en el valor de la expresión if:

fn main() {
    let x = 10;
    let size = if x < 20 { "pequeño" } else { "grande" };
    println!("tamaño del número: {}", size);
}

Bucles

Hay tres palabras clave de bucle en Rust: while, loop y for:

Bucles while

La palabra clave while es muy similar a la de otros lenguajes y ejecuta el cuerpo del bucle mientras que la condición sea valida.

fn main() {
    let mut x = 200;
    while x >= 10 {
        x = x / 2;
    }
    println!("x final: {x}");
}

for

El bucle for itera sobre rangos de valores o las entradas de una colección:

fn main() {
    for x in 1..5 {
        println!("x: {x}");
    }

    for elem in [1, 2, 3, 4, 5] {
        println!("elem: {elem}");
    }
}

loop

El bucle loop repite hasta encontrar un break.

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        println!("{i}");
        if i > 100 {
            break;
        }
    }
}

break y continue

Si quieres iniciar inmediatamente la siguiente iteración, usa continue.

Si quieres salir de un bucle antes de que termine, usa break. Para loop, este puede tomar una expresión opcional que se vuelve el valor de la expresión loop.

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        if i > 5 {
            break;
        }
        if i % 2 == 0 {
            continue;
        }
        println!("{}", i);
    }
}

Etiquetas

De forma opcional, tanto continue como break pueden utilizar un argumento de etiqueta para interrumpir los bucles anidados:

fn main() {
    let s = [[5, 6, 7], [8, 9, 10], [21, 15, 32]];
    let mut elements_searched = 0;
    let target_value = 10;
    'outer: for i in 0..=2 {
        for j in 0..=2 {
            elements_searched += 1;
            if s[i][j] == target_value {
                break 'outer;
            }
        }
    }
    print!("elementos travesados: {elements_searched}");
}

Bloques y ámbitos

Bloques

En Rust, un bloque contiene una secuencia de expresiones rodeados por llaves {}. Cada bloque tiene el tipo y valor de la última expresión del bloque:

fn main() {
    let z = 13;
    let x = {
        let y = 10;
        println!("y: {y}");
        z - y
    };
    println!("x: {x}");
}

Si la última expresión termina con ;, el tipo y el valor resultante será ().

Ámbitos y Shadowing

El ámbito de una variable se limita al bloque que la contiene.

Puedes sombrear variables, tanto las de ámbitos externos como las del propio ámbito:

fn main() {
    let a = 10;
    println!("antes: {a}");
    {
        let a = "hola";
        println!("ámbito interno: {a}");

        let a = true;
        println!("sombreado en el ámbito interno: {a}");
    }

    println!("después: {a}");
}

Funciones

fn gcd(a: u32, b: u32) -> u32 {
    if b > 0 {
        gcd(b, a % b)
    } else {
        a
    }
}

fn main() {
    println!("gcd: {}", gcd(143, 52));
}

Macros

Las macros se amplían a código de Rust durante la compilación y pueden adoptar un número variable de argumentos. Se distinguen por utilizar un símbolo ! al final. La biblioteca estándar de Rust incluye una serie de macros útiles.

• println!(format, ..) imprime una linea a la salida estándar ("standard output"), aplicando el formato descrito en std::fmt.
• format!(format, ..) funciona igual que println!, pero devuelve el resultado en forma de cadena.
• dbg!(expression) registra el valor de la expresión y lo devuelve.
• todo!() marca un fragmento de código como no implementado todavía. Si se ejecuta, activará un error pánico.
• unreachable!() marca un fragmento de código como inaccesible. Si se ejecuta, activará un error pánico.

fn factorial(n: u32) -> u32 {
    let mut product = 1;
    for i in 1..=n {
        product *= dbg!(i);
    }
    product
}

fn fizzbuzz(n: u32) -> u32 {
    todo!()
}

fn main() {
    let n = 4;
    println!("{n}! = {}", factorial(n));
}

Ejercicio: secuencia de Collatz

La secuencia de Collatz se define de la siguiente manera, para n₁ arbitrario mayor que cero:

• Si _n_i_es 1, la secuencia termina en n_i.
• Si n_i es par, n_i+1 = n_i / 2.
• Si n_i es impar, n_i+1 = 3 * n_i + 1.

Por ejemplo, empezando con n₁ = 3:

• 3 es impar, entonces n₂ = 3 * 3 + 1 = 10;
• 10 is par, entonces n₃ = 10 / 2 = 5;
• 5 es impar, entonces n₄ = 3 * 5 + 1 = 16;
• 16 es par, entonces n₅ = 16 / 2 = 8;
• 8 es par, entonces n₆ = 8 / 2 = 4;
• 44 es par, entonces n₇ = 4 / 2 = 2;
• 2 es par, entonces n₈ = 1; and
• la secuencia finaliza.

Escribe una función para calcular la longitud de la secuencia de Collatz para un número n inicial dado.

/// Determina la longitud de la secuencia de Collatz que empieza por `n`.
fn collatz_length(mut n: i32) -> u32 {
  todo!("Implementar esto")
}

fn main() {
  todo!("Implementar esto")
}

Solución

/// Determina la longitud de la secuencia de Collatz que empieza por `n`.
fn collatz_length(mut n: i32) -> u32 {
    let mut len = 1;
    while n > 1 {
        n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 };
        len += 1;
    }
    len
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Longitud: {}", collatz_length(11));
}

Te damos la bienvenida

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 35 minutos. Contiene:

Tuplas y arrays

Esta sección tiene una duración aproximada de 35 minutos. Contiene:

Arrays

fn main() {
    let mut a: [i8; 10] = [42; 10];
    a[5] = 0;
    println!("a: {a:?}");
}

Tuplas

fn main() {
    let t: (i8, bool) = (7, true);
    println!("t.0: {}", t.0);
    println!("t.1: {}", t.1);
}

Iteración de Arreglos (Arrays)

La instrucción for permite iterar sobre arrays, pero no sobre tuplas.

fn main() {
    let primes = [2, 3, 5, 7, 11, 13, 17, 19];
    for prime in primes {
        for i in 2..prime {
            assert_ne!(prime % i, 0);
        }
    }
}

Patrones y Desestructuración

Cuando uno trabaja con tuplas y otros valores estructurados, es común querer extraer valores interiores a variables locales. Uno puede manualmente acceder los valores interiores:

fn print_tuple(tuple: (i32, i32)) {
    let left = tuple.0;
    let right = tuple.1;
    println!("left: {left}, right: {right}");
}

Rust también provee la coincidencia de patrones para destructurar un valor en sus partes constituyentes:

fn print_tuple(tuple: (i32, i32)) {
    let (left, right) = tuple;
    println!("left: {left}, right: {right}");
}

Ejercicio: arrays anidados

Los arrays pueden contener otros arrays:

#![allow(unused)]
fn main() {
let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
}

¿Cuál es el tipo de esta variable?

Usa el método anterior para escribir una función transpose que transpone una matriz (convierte filas en columnas):

Copia el siguiente fragmento de código en https://play.rust-lang.org/ e implementa la función. Esta función solo opera sobre matrices 3x3.

// TODO: borra esto cuando termines de implementarlo.
#![allow(unused_variables, dead_code)]

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    unimplemented!()
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- el comentario hace que rustfmt añade una nueva línea
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matriz: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("traspuesto: {:#?}", transposed);
}

Solución

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    let mut result = [[0; 3]; 3];
    for i in 0..3 {
        for j in 0..3 {
            result[j][i] = matrix[i][j];
        }
    }
    result
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- el comentario hace que rustfmt añade una nueva línea
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matriz: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("traspuesto: {:#?}", transposed);
}

Referencias

Esta sección tiene una duración aproximada de 55 minutos. Contiene:

Enums compartidas

Una referencia ofrece una forma de acceder a otro valor sin asumir la responsabilidad del valor. También se denomina "préstamo". Las referencias compartidas son de solo lectura y los datos a los que se hace referencia no pueden cambiar.

fn main() {
    let a = 'A';
    let b = 'B';
    let mut r: &char = &a;
    println!("r: {}", *r);
    r = &b;
    println!("r: {}", *r);
}

Una referencia compartida a un tipo T tiene el tipo &T. Se crea un valor de referencia con el operador &. El operador * "desreferencia" una referencia, dando lugar a su valor.

Rust prohibirá estáticamente las referencias colgantes:

fn x_axis(x: &i32) -> &(i32, i32) {
    let point = (*x, 0);
    return &point;
}

Referencias exclusivas

Las referencias exclusivas, también denominadas referencias mutables, permiten cambiar el valor al que hacen referencia. Tienen el tipo &mut T.

fn main() {
    let mut point = (1, 2);
    let x_coord = &mut point.0;
    *x_coord = 20;
    println!("point: {point:?}");
}

Slices

Un slice ofrece una visión de una colección más amplia:

fn main() {
    let mut a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• Los slices toman prestados datos del tipo slice.
• Pregunta: ¿Qué ocurre si se modifica a[3] justo antes de imprimir s?

Cadenas de texto (Strings)

Ahora podemos entender los dos tipos de cadenas de Rust:

• &str es un slice de bytes codificados en UTF-8, parecido a &[u8].
• String es un buffer adueñado de bytes codificados en UTF-8, parecido a Vec<T>.

fn main() {
    let s1: &str = "mundo";
    println!("s1: {s1}");

    let mut s2: String = String::from("¡Hola ");
    println!("s2: {s2}");
    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[s2.len() - s1.len()..];
    println!("s3: {s3}");
}

Ejercicio: geometría

Crearemos algunas funciones de utilidad para la geometría tridimensional representando un punto como [f64;3]. Debes decidir las firmas de las funciones.

// Calcula la magnitud de un vector sumando los cuadrados de sus coordenadas
// y sacando la raíz cuadrada. Usa el método `sqrt()` para calcular la raíz cuadrada
//, como `v.sqrt()`.


fn magnitude(...) -> f64 {
    todo!()
}

// Normaliza un vector calculando su magnitud y dividiendo todas
// sus coordenadas entre esa magnitud.


fn normalize(...) {
    todo!()
}

// Usa `main` para comprobar lo que has hecho.

fn main() {
    println!("Magnitud de un vector unitario: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitud de {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitud de {v:?} después de la normalización: {}", magnitude(&v));
}

Solución

/// Calcula la magnitud del vector dado.
fn magnitude(vector: &[f64; 3]) -> f64 {
    let mut mag_squared = 0.0;
    for coord in vector {
        mag_squared += coord * coord;
    }
    mag_squared.sqrt()
}

/// Cambia la magnitud del vector a 1.0 sin cambiar su dirección.
fn normalize(vector: &mut [f64; 3]) {
    let mag = magnitude(vector);
    for item in vector {
        *item /= mag;
    }
}

fn main() {
    println!("Magnitud de un vector unitario: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitud de {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitud de {v:?} después de la normalización: {}", magnitude(&v));
}

Tipos definidos por el usuario

Esta sección tiene una duración aproximada de 50 minutos. Contiene:

Estructuras con nombre

Al igual que C y C++, Rust admite estructuras (struct) personalizadas:

struct Person {
    name: String,
    age: u8,
}

fn describe(person: &Person) {
    println!("{} tiene {} años", person.name, person.age);
}

fn main() {
    let mut peter = Person { name: String::from("Peter"), age: 27 };
    describe(&peter);

    peter.age = 28;
    describe(&peter);

    let name = String::from("Avery");
    let age = 39;
    let avery = Person { name, age };
    describe(&avery);

    let jackie = Person { name: String::from("Jackie"), ..avery };
    describe(&jackie);
}

Estructuras de tuplas

Si los nombres de los campos no son importantes, puedes utilizar una estructura de tuplas:

struct Point(i32, i32);

fn main() {
    let p = Point(17, 23);
    println!("({}, {})", p.0, p.1);
}

Esto se suele utilizar para envoltorios de campo único (denominados newtypes):

struct PoundsOfForce(f64);
struct Newtons(f64);

fn compute_thruster_force() -> PoundsOfForce {
    todo!("Pregunta a un científico aeroespacial de la NASA")
}

fn set_thruster_force(force: Newtons) {
    // ...
}

fn main() {
    let force = compute_thruster_force();
    set_thruster_force(force);
}

Enumeraciones

La palabra clave enum permite crear un tipo que tiene diferentes variantes:

#[derive(Debug)]
enum Direction {
    Left,
    Right,
}

#[derive(Debug)]
enum PlayerMove {
    Pass,                        // Variante simple
    Run(Direction),              // Variante de tupla
    Teleport { x: u32, y: u32 }, // Variante de struct
}

fn main() {
    let m: PlayerMove = PlayerMove::Run(Direction::Left);
    println!("En este turno: {:?}", m);
}

static

Las variables estáticas vivirán durante toda la ejecución del programa y, por lo tanto, no se moverán:

static BANNER: &str = "Bienvenide a RustOS 3.14";

fn main() {
    println!("{BANNER}");
}

Tal y como se indica en el libro Rust RFC Book, estas no son insertadas y tienen una ubicación de memoria real asociada. Esto resulta útil para código insertado y no seguro. Además, la variable continúa durante toda la ejecución del programa. Cuando un valor de ámbito global no tiene ningún motivo para necesitar identidad de objeto, se suele preferir const.

const

Las variables constantes se evalúan en tiempo de compilación y sus valores se insertan donde sean utilizados:

const DIGEST_SIZE: usize = 3;
const ZERO: Option<u8> = Some(42);

fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {
    let mut digest = [ZERO.unwrap_or(0); DIGEST_SIZE];
    for (idx, &b) in text.as_bytes().iter().enumerate() {
        digest[idx % DIGEST_SIZE] = digest[idx % DIGEST_SIZE].wrapping_add(b);
    }
    digest
}

fn main() {
    let digest = compute_digest("Hello");
    println!("digest: {digest:?}");
}

Según el libro Rust RFC Book, se insertan cuando se utilizan.

Sólo se pueden llamar a las funciones marcadas como const en tiempo de compilación para generar valores const. Sin embargo, las funciones const se pueden llamar en runtime.

Aliases de tipo

Un alias de tipo crea un nombre para otro tipo. Ambos tipos se pueden utilizar indistintamente.

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// Los alias resultan de más utilidad con tipos largos y complejos:
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

Ejercicio: eventos de ascensor

Crearemos una estructura de datos para representar un evento en un sistema de control de ascensores. Debes definir los tipos y las funciones para crear varios eventos. Usa #[derive(Debug)] para permitir que se aplique el formato {:?} a los tipos.

Para hacer este ejercicio solo es necesario crear y rellenar estructuras de datos de forma que main se ejecute sin errores. En la siguiente parte del curso veremos cómo extraer datos de estas estructuras.

#[derive(Debug)]
/// Un evento en el sistema de ascensores al que debe reaccionar el controlador.
enum Event {
    // TAREAS: añadir variantes obligatorias
}

/// Un sentido de la marcha.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// El ascensor ha llegado a la planta indicada.
fn car_arrived(floor: i32) -> Event {
    todo!()
}

/// Las puertas del ascensor se han abierto.
fn car_door_opened() -> Event {
    todo!()
}

/// Las puertas del ascensor se han cerrado.
fn car_door_closed() -> Event {
    todo!()
}

/// Se ha pulsado el botón direccional de un ascensor en la planta indicada.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    todo!()
}

/// Se ha pulsado el botón de una planta en el ascensor.
fn car_floor_button_pressed(floor: i32) -> Event {
    todo!()
}

fn main() {
    println!(
        "Un pasajero de la planta baja ha pulsado el botón para ir hacia arriba: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("El ascensor ha llegado a la planta baja: {:?}", car_arrived(0));
    println!("Las puertas del ascensor se han abierto: {:?}", car_door_opened());
    println!(
        "Un pasajero ha pulsado el botón de la tercera planta: {:?}",
        car_floor_button_pressed(3)
    );
    println!("Las puertas del ascensor se han cerrado: {:?}", car_door_closed());
    println!("El ascensor ha llegado a la tercera planta: {:?}", car_arrived(3));
}

Solución

#[derive(Debug)]
/// Un evento en el sistema de ascensores al que debe reaccionar el controlador.
enum Event {
    /// Se ha pulsado un botón.
    ButtonPressed(Button),

    /// El ascensor ha llegado a la planta indicada.
    CarArrived(Floor),

    /// Las puertas del ascensor se han abierto.
    CarDoorOpened,

    /// Las puertas del ascensor se han cerrado.
    CarDoorClosed,
}

/// Una planta se representa como un número entero.
type Floor = i32;

/// Un sentido de la marcha.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// Un botón accesible para el usuario.
#[derive(Debug)]
enum Button {
    /// Un botón para el ascensor en la planta indicada.
    LobbyCall(Direction, Floor),

    /// Un botón de planta de la cabina del ascensor.
    CarFloor(Floor),
}

/// El ascensor ha llegado a la planta indicada.
fn car_arrived(floor: i32) -> Event {
    Event::CarArrived(floor)
}

/// Las puertas del ascensor se han abierto.
fn car_door_opened() -> Event {
    Event::CarDoorOpened
}

/// Las puertas del ascensor se han cerrado.
fn car_door_closed() -> Event {
    Event::CarDoorClosed
}

/// Se ha pulsado el botón direccional de un ascensor en la planta indicada.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    Event::ButtonPressed(Button::LobbyCall(dir, floor))
}

/// Se ha pulsado el botón de una planta en el ascensor.
fn car_floor_button_pressed(floor: i32) -> Event {
    Event::ButtonPressed(Button::CarFloor(floor))
}

fn main() {
    println!(
        "Un pasajero de la planta baja ha pulsado el botón para ir hacia arriba: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("El ascensor ha llegado a la planta baja: {:?}", car_arrived(0));
    println!("Las puertas del ascensor se han abierto: {:?}", car_door_opened());
    println!(
        "Un pasajero ha pulsado el botón de la tercera planta: {:?}",
        car_floor_button_pressed(3)
    );
    println!("Las puertas del ascensor se han cerrado: {:?}", car_door_closed());
    println!("El ascensor ha llegado a la tercera planta: {:?}", car_arrived(3));
}

Te damos la bienvenida al día 2

Ahora que ya sabemos bastante sobre Rust, continuaremos con un enfoque en el sistema de tipos de Rust:

• Coincidencia de Patrones: desestructuración de enums, structs y arrays.
• Métodos: asociar funciones a tipos.
• Traits: comportamientos que comparten varios tipos.
• Genéricos: parametrizar tipos en otros tipos.
• Tipos y traits de bibliotecas estándar: un recorrido por la amplia biblioteca estándar de Rust.

Horario

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 10 minutos. Contiene:

Correspondencia de Patrones

Esta sección tiene una duración aproximada de 1 hora. Contiene:

Correspondencia de Valores

La palabra clave match te permite comparar un valor con uno o varios patrones. Las comparaciones se hacen de arriba a abajo y el primer patrón que coincida gana.

Los patrones pueden ser valores simples, del mismo modo que switch en C y C++:

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("Salir"),
        'a' | 's' | 'w' | 'd'     => println!("Desplazarse"),
        '0'..='9'                 => println!("Introducción de números"),
        key if key.is_lowercase() => println!("Minúscula: {key}"),
        _                         => println!("Otro"),
    }
}

_ es un patrón comodín que coincide con cualquier valor. Las expresiones deben ser exhuastivas, lo que significa que deben tener en cuenta todas las posibilidades, por lo que _ a menudo se usa como un caso final que atrapa todo.

Match puede ser usado como una expresión. Al igual que con if let, cada brazo de coincidencia debe ser del mismo tipo. El tipo es la última expresión del bloque, si la hay. En el ejemplo anterior, el tipo es ().

Una variable del patrón (en este ejemplo, key) creará un enlace que se puede usar dentro del brazo de coincidencia.

Un protección de coincidencia hace que la expresión coincida únicamente si se cumple la condición.

Structs

Al igual que las tuplas, las estructuras se pueden desestructurar con la coincidencia:

struct Foo {
    x: (u32, u32),
    y: u32,
}

#[rustfmt::skip]
fn main() {
    let foo = Foo { x: (1, 2), y: 3 };
    match foo {
        Foo { x: (1, b), y } => println!("x.0 = 1, b = {b}, y = {y}"),
        Foo { y: 2, x: i }   => println!("y = 2, x = {i:?}"),
        Foo { y, .. }        => println!("y = {y}, se han ignorado otros campos"),
    }
}

Enumeraciones

Al igual que las tuplas, las enumeraciones también se pueden desestructurar con la coincidencia:

Los patrones también se pueden usar para enlazar variables a partes de los valores. Así es como se inspecciona la estructura de tus tipos. Empecemos con un tipo enum sencillo:

enum Result {
    Ok(i32),
    Err(String),
}

fn divide_in_two(n: i32) -> Result {
    if n % 2 == 0 {
        Result::Ok(n / 2)
    } else {
        Result::Err(format!("no se puede dividir {n} en dos partes iguales"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} dividido entre dos es {half}"),
        Result::Err(msg) => println!("se ha producido un error: {msg}"),
    }
}

Aquí hemos utilizado los brazos para desestructurar el valor de Result. En el primer brazo, half está vinculado al valor que hay dentro de la variante Ok. En el segundo, msg está vinculado al mensaje de error.

Control de Flujo Let

Rust tiene algunas construcciones de control de flujo que difieren de otros lenguajes. Se utilizan para el patrón de coincidencia:

• Expresiones if let
• Expresiones let else
• Expresiones while let

Expresiones if let

La [expresión if let][(https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions) te permite ejecutar código diferente en función de si un valor coincide con un patrón:

use std::time::Duration;

fn sleep_for(secs: f32) {
    if let Ok(dur) = Duration::try_from_secs_f32(secs) {
        std::thread::sleep(dur);
        println!("Horas de sueño: {:?}", dur);
    }
}

fn main() {
    sleep_for(-10.0);
    sleep_for(0.8);
}

Expresiones let else

En el caso habitual de coincidencia con un patrón y retorno de la función, utiliza let else. El caso "else" debe divergir (return, break o pánico; cualquier acción es válida menos colocarlo al final del bloque).

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let s = if let Some(s) = maybe_string {
        s
    } else {
        return Err(String::from("se ha obtenido None"));
    };

    let first_byte_char = if let Some(first_byte_char) = s.chars().next() {
        first_byte_char
    } else {
        return Err(String::from("se ha encontrado una cadena vacía"));
    };

    if let Some(digit) = first_byte_char.to_digit(16) {
        Ok(digit)
    } else {
        Err(String::from("no es un dígito hexadecimal"))
    }
}

fn main() {
    println!("resultado: {:?}", hex_or_die_trying(Some(String::from("foo"))));
}

Al igual que con if let, hay una variante while let que prueba repetidamente un valor con respecto a un patrón:

fn main() {
    let mut name = String::from("Comprehensive Rust 🦀");
    while let Some(c) = name.pop() {
        println!("character: {c}");
    }
    // (There are more efficient ways to reverse a string!)
}

Aquí, String::pop devolverá Some(c) hasta que la cadena este vacía, cuando empezara a devolver None. while let nos permite seguir iterando a través de todos los elementos.

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("se ha obtenido None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("se ha encontrado una cadena vacía"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("no es un dígito hexadecimal"));
    };

    return Ok(digit);
}
}

Ejercicio: evaluación de expresiones

Vamos a escribir un sencillo evaluador recursivo de expresiones aritméticas.

El tipo Box es un puntero inteligente y lo veremos con detalle más adelante en el curso. Una expresión puede "estar delimitada" con Box::new, tal como se observa en las pruebas. Para evaluar una expresión delimitada, usa el operador de desreferencia (*) para "eliminar la delimitación": eval(*boxed_expr).

Algunas expresiones no se pueden evaluar y devuelven un error. El tipo estándar Result<Value, String> es una enumeración que representa un valor correcto (Ok(Value)) o un error (Err(String)). Más adelante hablaremos de este tipo en profundidad.

Copia y pega el código en el playground de Rust y comienza a implementar eval. El producto final debe superar las pruebas. Recomendamos utilizar todo!() y hacer las pruebas para superar todas las pruebas de forma individual. También puedes saltarte una prueba de forma temporal con #[ignore]:

#[test]
#[ignore]
fn test_value() { .. }

Si terminas antes, prueba a escribir una prueba que dé como resultado la división entre cero o un desbordamiento de números enteros. ¿Cómo podrías gestionarlo con Result en vez de con un pánico?

#![allow(unused)]
fn main() {
/// Operación que se puede llevar a cabo en dos subexpresiones.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Una expresión en forma de árbol.
#[derive(Debug)]
enum Expression {
    /// Operación en dos subexpresiones.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Un valor literal
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    todo!()
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("división entre cero"))
    );
}
}

Solución

/// Operación que se puede llevar a cabo en dos subexpresiones.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Una expresión en forma de árbol.
#[derive(Debug)]
enum Expression {
    /// Operación en dos subexpresiones.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Un valor literal
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    match e {
        Expression::Op { op, left, right } => {
            let left = match eval(*left) {
                Ok(v) => v,
                e @ Err(_) => return e,
            };
            let right = match eval(*right) {
                Ok(v) => v,
                e @ Err(_) => return e,
            };
            Ok(match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => {
                    if right == 0 {
                        return Err(String::from("división entre cero"));
                    } else {
                        left / right
                    }
                }
            })
        }
        Expression::Value(v) => Ok(v),
    }
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("división entre cero"))
    );
}

fn main() {
    let expr = Expression::Op {
        op: Operation::Sub,
        left: Box::new(Expression::Value(20)),
        right: Box::new(Expression::Value(10)),
    };
    println!("expr: {:?}", expr);
    println!("resultado: {:?}", eval(expr));
}

Métodos y Traits

Esta sección tiene una duración aproximada de 50 minutos. Contiene:

Métodos

Rust te permite asociar funciones a los nuevos tipos. Para ello, usa un bloque impl:

#[derive(Debug)]
struct Race {
    name: String,
    laps: Vec<i32>,
}

impl Race {
    // No hay receptor, método estático
    fn new(name: &str) -> Self {
        Self { name: String::from(name), laps: Vec::new() }
    }

    // Acceso exclusivo de lectura/escritura prestado a self
    fn add_lap(&mut self, lap: i32) {
        self.laps.push(lap);
    }

    // Acceso compartido y de solo lectura prestado a self
    fn print_laps(&self) {
        println!("Se han registrado {} vueltas de {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Vuelta {idx}: {lap} s");
        }
    }

    // Propiedad exclusiva de self
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("La carrera {} ha terminado. Duración total de la vuelta: {}.", self.name, total);
    }
}

fn main() {
    let mut race = Race::new("Gran Premio de Mónaco");
    race.add_lap(70);
    race.add_lap(68);
    race.print_laps();
    race.add_lap(71);
    race.print_laps();
    race.finish();
    // race.add_lap(42);
}

El argumento self denomina el "receiver" (receptor) - el objeto sobre cual el método actuará. Hay varios receivers comunes para un método:

• &self: toma prestado el objeto del llamador utilizando una referencia compartida e inmutable. El objeto se puede volver a utilizar después.
• &mut self: toma prestado el objeto del llamador mediante una referencia única y mutable. El objeto se puede volver a utilizar después.
• self: asume el ownership del objeto y lo aleja del llamador. El método se convierte en el propietario del objeto. El objeto se eliminará (es decir, se anulará la asignación) cuando el método devuelva un resultado, a menos que se transmita su ownership de forma explícita. El ownership completa no implica automáticamente una mutabilidad.
• mut self: igual que lo anterior, pero el método puede mutar el objeto.
• Sin receptor: se convierte en un método estático de la estructura. Normalmente se utiliza para crear constructores que se suelen denominar new.

Traits

Rust te permite abstraer sobre tipos con traits. Son similares a las interfaces:

trait Pet {
    /// Devuelve una frase de esta mascota.
    fn talk(&self) -> String;

    /// Imprime un saludo a la mascota en una salida estándar.
    fn greet(&self);
}

Implementación de Traits

trait Pet {
    fn talk(&self) -> String;

    fn greet(&self) {
        println!("¡Eres una monada! ¿Cómo te llamas? {}", self.talk());
    }
}

struct Dog {
    name: String,
    age: i8,
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("¡Guau, me llamo {}!", self.name)
    }
}

fn main() {
    let fido = Dog { name: String::from("Fido"), age: 5 };
    fido.greet();
}

Supertraits

Un trait puede requerir que los tipos que lo implementan también implementen otros traits, llamados supertraits. Aquí, cualquier tipo implementando Pet también debe implementar Animal.

trait Animal {
    fn leg_count(&self) -> u32;
}

trait Pet: Animal {
    fn name(&self) -> String;
}

struct Dog(String);

impl Animal for Dog {
    fn leg_count(&self) -> u32 {
        4
    }
}

impl Pet for Dog {
    fn name(&self) -> String {
        self.0.clone()
    }
}

fn main() {
    let puppy = Dog(String::from("Rex"));
    println!("{} tiene {} piernas", puppy.name(), puppy.leg_count());
}

Tipos de datos asociados

Tipos asociados son tipos guarda-espacio que han sido proveídos por la implementación del trait.

#[derive(Debug)]
struct Meters(i32);
#[derive(Debug)]
struct MetersSquared(i32);

trait Multiply {
    type Output;
    fn multiply(&self, other: &Self) -> Self::Output;
}

impl Multiply for Meters {
    type Output = MetersSquared;
    fn multiply(&self, other: &Self) -> Self::Output {
        MetersSquared(self.0 * other.0)
    }
}

fn main() {
    println!("{:?}", Meters(10).multiply(&Meters(20)));
}

Derivación de Traits

Los traits compatibles se pueden implementar de forma automática en los tipos personalizados de la siguiente manera:

#[derive(Debug, Clone, Default)]
struct Player {
    name: String,
    strength: u8,
    hit_points: u8,
}

fn main() {
    let p1 = Player::default(); // El trait predeterminado añade el constructor `default`.
    let mut p2 = p1.clone(); // El trait clonado añade el método `clone`.
    p2.name = String::from("EldurScrollz");
    // El trait Debug permite que sea compatible con imprimir con `{:?}`.
    println!("{:?} contra {:?}", p1, p2);
}

Ejercicio: trait de registro

Vamos a diseñar una sencilla utilidad de registro mediante un trait Logger con un método log. El código que podría registrar su progreso puede usar &impl Logger. En las pruebas, esta acción colocaría mensajes en el archivo de registro de la prueba, mientras que en una compilación de producción enviaría los mensajes a un servidor de registro.

Sin embargo, el elemento StderrLogger que aparece a continuación registra todos los mensajes, independientemente de su verbosidad. Tu tarea es escribir un tipo VerbosityFilter que ignore los mensajes que superen el máximo de verbosidad.

Este es un patrón común: una struct que envuelve una implementación de traits e implementa ese mismo trait, añadiendo comportamiento en el proceso. ¿Qué otros tipos de envoltorios pueden ser útiles en una utilidad de registro?

use std::fmt::Display;

pub trait Logger {
    /// Registra un mensaje con el nivel de verbosidad determinado.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosidad={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "Para tu información");
    logger.log(2, "Oh, oh");
}

// TAREA: Define e implementa `VerbosityFilter`.

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

Solución

use std::fmt::Display;

pub trait Logger {
    /// Registra un mensaje con el nivel de verbosidad determinado.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosidad={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "Para tu información");
    logger.log(2, "Oh, oh");
}

/// Registra solo los mensajes que cumplan el nivel de verbosidad determinado.
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StderrLogger,
}

impl Logger for VerbosityFilter {
    fn log(&self, verbosity: u8, message: impl Display) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

Te damos la bienvenida

Incluyendo descansos de 10 minutos, esta sesión debería durar unas 3 horas y 15 minutos. Contiene:

Genéricos

Esta sección tiene una duración aproximada de 45 minutos. Contiene:

Funciones genéricas

Rust admite el uso de genéricos, lo que permite abstraer los algoritmos o las estructuras de datos (como el ordenamiento o un árbol binario) sobre los tipos utilizados o almacenados.

/// Elige `even` u `odd` en función de si `n` es par o impar.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("número elegido: {:?}", pick(97, 222, 333));
    println!("tupla elegida: {:?}", pick(28, ("perro", 1), ("gato", 2)));
}

Tipos de Datos Genéricos

Puedes usar genéricos para abstraer el tipo de campo concreto:

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    fn set_x(&mut self, x: T) {
        self.x = x;
    }
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} y {float:?}");
    println!("coordenadas: {:?}", integer.coords());
}

Traits Genéricos

Los traits también pueden ser genéricos, como los tipos y las funciones. Los parámetros de un trait obtienen tipos concretos cuando es usado.

#[derive(Debug)]
struct Foo(String);

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("Convertido del numero entero: {from}"))
    }
}

impl From<bool> for Foo {
    fn from(from: bool) -> Foo {
        Foo(format!("Convertido del bool: {from}"))
    }
}

fn main() {
    let from_int = Foo::from(123);
    let from_bool = Foo::from(true);
    println!("{from_int:?}, {from_bool:?}");
}

Trait Bounds

Cuando se trabaja con genéricos, a menudo se prefiere que los tipos implementen algún trait, de forma que se pueda llamar a los métodos de este trait.

Puedes hacerlo con T: Trait o impl Trait:

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

// struct NotClonable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

impl Trait

De forma similar a los límites de traits, se puede usar la sintaxis impl Trait en argumentos de funciones y valores devueltos:

// Azúcar sintáctico para:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("depurable: {debuggable:?}");
}

dyn Trait

En adición a ser usados para despacho estático con genéricos, los traits también se pueden usar para despacho dinámico/tipo-borrado con objetos de trait:

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("¡Guau, me llamo {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("¡Miau!")
    }
}

// Utiliza genéricos y despacho estático.
fn generic(pet: &impl Pet) {
    println!("Hola, quien eres? {}", pet.talk());
}

// Utiliza borradura de tipos y despacho dinámico.
fn dynamic(pet: &dyn Pet) {
    println!("Hola, quien eres? {}", pet.talk());
}

fn main() {
    let cat = Cat { lives: 9 };
    let dog = Dog { name: String::from("Fido"), age: 5 };

    generic(&cat);
    generic(&dog);

    dynamic(&cat);
    dynamic(&dog);
}

Ejercicio: min genérico

En este breve ejercicio, implementarás una función min genérica que determina el mínimo de dos valores mediante el trait Ord.

use std::cmp::Ordering;

// TAREA: implementar la función `min` usada en `main`.

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hola", "adios"), "adios");
    assert_eq!(min("murciélago", "armadillo"), "armadillo");
}

Solución

use std::cmp::Ordering;

fn min<T: Ord>(l: T, r: T) -> T {
    match l.cmp(&r) {
        Ordering::Less | Ordering::Equal => l,
        Ordering::Greater => r,
    }
}

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hola", "adios"), "adios");
    assert_eq!(min("murciélago", "armadillo"), "armadillo");
}

Tipos de la Biblioteca Estándar

Esta sección tiene una duración aproximada de 1 hora. Contiene:

Biblioteca estándar

Rust viene con una biblioteca estándar que ayuda a establecer un conjunto de tipos comunes que se usan en la biblioteca y los programas de Rust. De esta forma, dos bibliotecas pueden funcionar juntas sin problemas, puesto que ambas utilizan el mismo tipo String.

De hecho, Rust contiene varias capas de la biblioteca estándar: core, alloc y std.

• core incluye los tipos y funciones más básicos que no dependen de libc, de un allocator (asignador de memoria) ni de la presencia de un sistema operativo.
• alloc incluye tipos que requieren un allocator de heap global, como Vec, Box y Arc.
• Las aplicaciones embebidas en Rust menudo solo usan core y a algunas veces alloc.

Documentación

Rust incluye una amplia documentación. Por ejemplo:

• Todos los detalles sobre bucles.
• Tipos primitivos como u8.
• Tipos de la biblioteca estándar como Option o BinaryHeap.

De hecho, puedes documentar tu propio código:

/// Determina si el primer argumento es divisible por el segundo argumento.
///
/// Si el segundo es cero, el resultado será false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

El contenido se trata como Markdown. Todos los crates de la biblioteca de Rust publicados se documentan automáticamente en docs.rs mediante la herramienta rustdoc. Es propio documentar todos los elementos públicos de una API usando este patrón.

Para documentar un elemento desde dentro (por ejemplo, dentro de un módulo), utiliza //! o /*! .. */, denominado como "comentarios internos del documento":

//! Este módulo contiene funciones relacionadas con la divisibilidad de números enteros.

Option

Ya hemos visto algunos usos de Option<T>. Almacena un valor de tipo T o nada. Por ejemplo, String::find devuelve un Option<usize>.

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("buscar {position:?} devuelto");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("buscar {position:?} devuelto");
    assert_eq!(position.expect("No se ha encontrado el carácter"), 0);
}

Result

Result es parecido a Option, pero indica si una operación se ha completado de forma correcta o ha fallado, cada una con un tipo diferente. Es genérico: Result<T, E> donde T es usado en el variante Ok y E en el variante Err.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Querido diario: {contents} ({bytes} bytes)");
            } else {
                println!("No se ha podido leer el contenido del archivo");
            }
        }
        Err(err) => {
            println!("No se ha podido abrir el diario: {err}");
        }
    }
}

String

String es el búfer de cadena ampliable UTF-8 estándar:

fn main() {
    let mut s1 = String::new();
    s1.push_str("Hola");
    println!("s1: longitud = {}, capacidad = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: longitud= {}, capacidad = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇨🇭");
    println!("s3: longitud = {}, número de caracteres = {}", s3.len(), s3.chars().count());
}

String implementa [Deref<Target = str>][2], lo que significa que puedes llamar a todos los métodos str en una String.

Vec (Vectores)

Vec es el búfer estándar redimensionable asignado al heap:

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: longitud= {}, capacidad = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: longitud= {}, capacidad = {}", v2.len(), v2.capacity());

    // Macro canónica para inicializar un vector con elementos.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Conserva solo los elementos pares.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Elimina los duplicados consecutivos.
    v3.dedup();
    println!("{v3:?}");
}

Vec implementa Deref<Target = [T]>, lo que significa que puedes llamar a métodos slice en un Vec.

HashMap

Mapa hash estándar con protección frente a ataques HashDoS:

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Las aventuras de Huckleberry Finn", 207);
    page_counts.insert("Los cuentos de los hermanos Grimm", 751);
    page_counts.insert("Orgullo y prejuicio", 303);

    if !page_counts.contains_key("Los miserables") {
        println!(
            "Tenemos información acerca de {} libros, pero no de Los miserables.",
            page_counts.len()
        );
    }

    for book in ["Orgullo y prejuicio", "Las aventuras de Alicia en el país de las maravillas"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} páginas"),
            None => println!("{book} es desconocido."),
        }
    }

    // Utiliza el método .entry() para insertar un valor si no se encuentra ningún resultado.
    for book in ["Orgullo y prejuicio", "Las aventuras de Alicia en el país de las maravillas"] {
        let page_count: &mut i32 = page_counts.entry(book).or_insert(0);
        *page_count += 1;
    }

    println!("{page_counts:#?}");
}

Ejercicio: Contador

En este ejercicio habrá una estructura de datos muy sencilla y la convertirás en genérica. Utiliza un std::collections::HashMap para hacer un seguimiento de los valores se han visto y cuántas veces ha aparecido cada uno.

La versión inicial de Counter está codificada para que solo funcione con los valores u32. Haz que struct y sus métodos sean genéricos sobre el tipo de valor del que se está haciendo un seguimiento, de manera que Counter pueda hacer el seguimiento de cualquier tipo de valor.

Si te sobra tiempo, prueba a usar el método entry para reducir a la mitad el número de búsquedas de hash que se necesita para implementar el método count.

use std::collections::HashMap;

/// Counter cuenta el número de veces que se ha visto cada valor de tipo T.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Crea un nuevo Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Cuenta una repetición del valor dado.
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// Devuelve el número de veces que se ha visto el valor dado.
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("se han visto {} valores iguales a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("manzana");
    strctr.count("naranja");
    strctr.count("manzana");
    println!("se han visto {} manzanas", strctr.times_seen("manzana"));
}

Solución

use std::collections::HashMap;
use std::hash::Hash;

/// Counter cuenta el número de veces que se ha visto cada valor de tipo T.
struct Counter<T> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Crea un nuevo Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Cuenta una repetición del valor dado.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Devuelve el número de veces que se ha visto el valor dado.
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("se han visto {} valores iguales a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("manzana");
    strctr.count("naranja");
    strctr.count("manzana");
    println!("se han visto {} manzanas", strctr.times_seen("manzana"));
}

Traits de la biblioteca estándar

Esta sección tiene una duración aproximada de 1 hora y 10 minutos. Contiene:

Comparaciones

Estos traits permiten comparar valores. Se pueden derivar todos los traits de los tipos que contengan campos que implementen estos traits.

PartialEq y Eq

PartialEq es una relación de equivalencia parcial, con el método requerido eq y el método proporcionado ne. Los operadores == y != llamarán a estos métodos.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq es una relación de equivalencia completa (reflexiva, simétrica y transitiva) e implica PartialEq. Las funciones que requieren una equivalencia total usan Eq como límite del trait.

PartialOrd y Ord

PartialOrd define un orden parcial, con un método partial_cmp. Se usa para implementar los operadores <, <=, >= y >.

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord es un orden total en el que cmp devuelve Ordering.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq<u32> for Key {
    fn eq(&self, other: &u32) -> bool {
        self.id == *other
    }
}

Operadores

La sobrecarga de operadores se implementa mediante traits en std::ops:

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{:?} + {:?} = {:?}", p1, p2, p1 + p2);
}

From e Into

Los tipos implementan From y Into para facilitar las conversiones de tipos:

fn main() {
    let s = String::from("hola");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

Into se implementa automáticamente cuando se implementa From:

fn main() {
    let s: String = "hola".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

Probando

Rust no tiene conversiones de tipo implícitas, pero admite conversiones explícitas con as. Por lo general, se definen según la semántica de C.

fn main() {
    let value: i64 = 1000;
    println!("ya que u16: {}", value as u16);
    println!("ya que i16: {}", value as i16);
    println!("ya que u8: {}", value as u8);
}

Los resultados de as se definen siempre en Rust y son coherentes en todas las plataformas. Es posible que no coincida con tu idea de cambiar el signo o convertirlo a otro de menor tamaño. Consulta los documentos y/o pregunta si tienes cualquier duda.

La conversión con as es una herramienta relativamente precisa y fácil de usar de forma incorrecta. Puede ser una fuente de pequeños errores, ya que los futuros trabajos de mantenimiento cambian los tipos que se usan o los intervalos de valores de los tipos. Las conversiones se utilizan únicamente cuando se quiere indicar un truncamiento incondicional (por ejemplo, seleccionando los 32 bits inferiores de un u64 con as u32, independientemente del elemento que se encontrase en los bits altos).

En el caso de las conversiones que no sean falibles (por ejemplo, u32 a u64), se recomienda utilizar From o Into en lugar de as para confirmar que la conversión es precisamente infalible. En el caso de las conversiones falibles, TryFrom y TryInto están disponibles cuando necesitas gestionar conversiones que se ajustan de forma diferente a las que no lo hacen.

Read y Write

Usando Read y BufRead, se puede abstraer sobre fuentes u8:

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("líneas en el slice: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("líneas en el archivo: {}", count_lines(file));
    Ok(())
}

De forma similar, Write te permite abstraer sobre fuentes u8:

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "Hola")?;
    log(&mut buffer, "mundo")?;
    println!("Registrado: {:?}", buffer);
    Ok(())
}

El trait Default

El trait Default produce un valor predeterminado para un tipo.

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Ya está configurado.".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

Cierres

Los cierres o expresiones lambda tienen tipos que no pueden nombrarse. Sin embargo, implementan traits especiales Fn, FnMut y FnOnce:

fn apply_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {
    println!("Llamado función sobre {input}");
    func(input)
}

fn main() {
    let add_3 = |x| x + 3;
    println!("add_3: {}", apply_with_log(add_3, 10));
    println!("add_3: {}", apply_with_log(add_3, 20));

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    println!("accumulate: {}", apply_with_log(&mut accumulate, 4));
    println!("accumulate: {}", apply_with_log(&mut accumulate, 5));

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    println!("multiply_sum: {}", apply_with_log(multiply_sum, 3));
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("¿Qué".to_string());
    hi("Greg");
}

Ejercicio: ROT13

En este ejemplo, implementaremos el algoritmo de cifrado clásico "ROT13". Copia este código en el playground e implementa los bits que faltan. Rota únicamente los caracteres alfabéticos ASCII para asegurarte de que el resultado sigue siendo válido en UTF-8.

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// Implementa el trait `Read` para `RotDecoder`.

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

¿Qué ocurre si encadenas dos instancias RotDecoder y cada una de ellas rota 13 posiciones?

Solución

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

Te damos la Bienvenida al Día 3

Hoy trataremos los siguientes puntos:

• Gestión de la memoria, lifetimes y el borrow checker: cómo garantiza Rust la seguridad de la memoria.
• Punteros inteligentes: tipos de punteros de biblioteca estándar.

Horario

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 20 minutos. Contiene:

Manejo de Memoria

Esta sección tiene una duración aproximada de 1 hora. Contiene:

Revisión de la memoria de programas

Los programas asignan memoria de dos formas:

• Stack: Zona de memoria continua para las variables locales.

  • Los valores tienen tamaños fijos conocidos en tiempo de compilación.
  • Muy rápida: mueve el stack pointer.
  • Fácil de gestionar: sigue las llamadas de funciones.
  • Excelente localidad de memoria.

• Heap: almacenamiento de valores fuera de las llamadas de funciones.

  • Los valores tienen tamaños dinámicos determinados en runtime.
  • Ligeramente más lento que el stack: requiere cierta trazabilidad.
  • No se puede asegurar la localidad de la memoria.

Ejemplo

Al crear un String, los metadatos de tamaño fijo se colocan en la stack y los datos de tamaño dinámico (la cadena real) en el heap:

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

fn main() {
    let mut s1 = String::from("Hola");
    s1.push(' ');
    s1.push_str("mundo");
    // ¡NO HAGÁIS ESTO EN CASA! Solo con fines educativos.
    // La cadena no proporciona garantías sobre su diseño, por lo que podría desencadenar
    // un comportamiento indefinido.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacidad = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

Métodos de Gestión de Memoria

Tradicionalmente, los lenguajes se dividen en dos grandes categorías:

• Control total a través de la gestión manual de la memoria: C, C++, Pascal, etc.
  • El programador decide cuándo asignar o liberar memoria del montículo.
  • El programador debe determinar si un puntero aún apunta a una memoria válida.
  • Los estudios demuestran que los programadores cometen errores.
• Seguridad total mediante la gestión automática de la memoria en runtime: Java, Python, Go, Haskell, etc.
  • Un sistema de tiempo de ejecución asegura que la memoria no se libera hasta que ya no se pueda hacer referencia a ella.
  • Normalmente se implementa con un contador de referencias, la recolección de elementos no utilizados o RAII.

Rust ofrece una mezcla de ambas:

Control completo y seguridad completa gracias a que el compilador se encarga del manejo correcto de la memoria.

Para ello, se utiliza un concepto de ownership (propiedad) explícito.

Ownership

Todos los enlaces a variables tienen un ámbito donde son válidos y se produce un error cuando se usan fuera de él:

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

Decimos que el valor pertenece a la variable. Cada valor en Rust tiene exactamente un dueño en todo tiempo.

Al final del ámbito, la variable se elimina y los datos se liberan. Un destructor puede correr en este momento para librar recursos.

Semántica de movimiento

Una asignación transferirá su ownership entre variables:

fn main() {
    let s1: String = String::from("¡Hola!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

• La asignación de s1 a s2 transfiere el ownership.
• Cuando s1 queda fuera del ámbito, no ocurre nada: no le pertenece nada.
• Cuando s2 sale del ámbito, los datos de la cadena se liberan.

Antes de mover a s2:

Después de mover a s2:

Cuando pasas un valor a una función, el valor se asigna al parámetro de la función. Esta acción transfiere el ownership:

fn say_hello(name: String) {
    println!("Hola {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Duplica los datos en s1.

Trait Clone

Cuando queramos hacer una copia de un valor, podemos hacerlo con el trait Clone.

fn say_hello(name: String) {
    println!("Hola {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name.clone());
    say_hello(name);
}

Tipos Copy

Aunque la semántica de movimiento es la opción predeterminada, algunos tipos se copian de forma predeterminada:

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

Estos tipos implementan el trait Copy.

Puedes habilitar tus propios tipos para que usen la semántica de copia:

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• Después de la asignación, tanto p1 como p2 tienen sus propios datos.
• También podemos utilizar p1.clone() para copiar los datos de forma explícita.

El Trait Drop

Los valores que implementan Drop pueden especificar el código que se ejecutará cuando salgan del ámbito:

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Suprimiendo {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "b" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Saliendo del bloque B");
        }
        println!("Saliendo del bloque A");
    }
    drop(a);
    println!("Saliendo de la página principal");
}

Ejercicio: Constructores

En este ejemplo, implementaremos un tipo de datos complejo que posee todos sus datos. Utilizaremos el "patrón de compilación" para permitir la compilación de un nuevo valor parte por parte mediante funciones prácticas.

Rellena las partes que faltan.

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Una representación de un paquete de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Devuelve una representación de este paquete como una dependencia para usarla
    /// en la compilación de otros paquetes.
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// Un compilador para un Package. Usa `build()` para crear el `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// Define la versión del paquete.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Define los autores del paquete.
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// Añade una dependencia adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Define el idioma. Si no se define, el idioma predeterminado será None.
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("registro: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Solución

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Una representación de un paquete de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Devuelve una representación de este paquete como una dependencia para usarla
    /// en la compilación de otros paquetes.
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// Un compilador para un Package. Usa `build()` para crear el `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: vec![],
            dependencies: vec![],
            language: None,
        })
    }

    /// Define la versión del paquete.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Define los autores del paquete.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Añade una dependencia adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Define el idioma. Si no se define, el idioma predeterminado será None.
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("registro: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Punteros inteligentes

Esta sección tiene una duración aproximada de 55 minutos. Contiene:

Box<T>

Box es un puntero propio de datos en el heap:

fn main() {
    let five = Box::new(5);
    println!("cinco: {}", *five);
}

Box<T> implementa Deref<Target = T>, lo que significa que puedes llamar a métodos desde T directamente en un Box<T>.

Los tipos de datos recursivos o los tipos de datos con tamaños dinámicos deben utilizar un Box:

#[derive(Debug)]
enum List<T> {
    /// Una lista no vacía: el primer elemento y el resto de la lista.
    Element(T, Box<List<T>>),
    /// Una lista vacía.
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

use std::mem::size_of_val;

struct Item(String);

fn main() {
    let just_box: Box<Item> = Box::new(Item("Solo box".into()));
    let optional_box: Option<Box<Item>> =
        Some(Box::new(Item("Box opcional".into())));
    let none: Option<Box<Item>> = None;

    assert_eq!(size_of_val(&just_box), size_of_val(&optional_box));
    assert_eq!(size_of_val(&just_box), size_of_val(&none));

    println!("Tamaño de just_box: {}", size_of_val(&just_box));
    println!("Tamaño de optional_box: {}", size_of_val(&optional_box));
    println!("Tamaño de none: {}", size_of_val(&none));
}

Rc

Rc es un puntero compartido de referencia contada. Utilízalo cuando necesites hacer referencia a los mismos datos desde varios lugares:

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• Consulta Arc y Mutex si te encuentras en un contexto multihilo.
• Puedes degradar un puntero compartido en un puntero Weak para crear ciclos que se abandonarán.

Objetos Trait Poseídos

Previamente vimos que objetos de trait se pueden usar con referencias, e.g. &dyn Pet. También podemos usar objetos de trait con punteros inteligentes como Box para crear objetos de trait con dueño: Box<dyn Pet>.

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("¡Guau, me llamo {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("¡Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Fido"), age: 5 }),
    ];
    for pet in pets {
        println!("Hola, quien eres? {}", pet.talk());
    }
}

Diseño de la memoria después de asignar pets:

Ejercicio: Árbol binario

Un árbol binario es una estructura de datos de tipo árbol en la que cada nodo tiene dos elementos secundarios (izquierda y derecha). Crearemos un árbol en el que cada nodo almacene un valor. Para un nodo N dado, todos los nodos del subárbol izquierdo de N contienen valores más pequeños, mientras que todos los nodos del subárbol derecho de N contendrán valores de mayor tamaño.

Implementa los siguientes tipos para superar las pruebas correspondientes.

Ejercicio adicional: implementar un iterador sobre un árbol binario que devuelva los valores en orden.

/// Un nodo del árbol binario.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Un subárbol posiblemente vacío.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Contenedor que almacena un conjunto de valores mediante un árbol binario.
///
/// Si se añade el mismo valor varias veces, solo se almacena una vez.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

// Implementa `new`, `insert`, `len` y `has` para `Subtree`.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // No es un elemento único.
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Solución

use std::cmp::Ordering;

/// Un nodo del árbol binario.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Un subárbol posiblemente vacío.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Contenedor que almacena un conjunto de valores mediante un árbol binario.
///
/// Si se añade el mismo valor varias veces, solo se almacena una vez.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // No es un elemento único.
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Te damos la bienvenida

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de una horas y 55 minutos. Contiene:

Préstamos (Borrowing)

Esta sección tiene una duración aproximada de 55 minutos. Contiene:

Emprestar (borrow) un valor

En lugar de transferir el ownership (posesión) al llamar a una función, puedes permitir que una función tome prestado el valor:

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• La función add toma prestados dos puntos y devuelve uno nuevo.
• El llamador conserva el ownership de las entradas.

Verificación de Préstamos

El borrow checker de Rust limita las formas en que se pueden tomar prestados valores. Para un dado valor, en cualquier tiempo:

• Puedes tener uno o varios valores &T, o
• Solo puedes tener exactamente una referencia exclusiva al valor.

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

Errores de Préstamo

Como un ejemplo concreto de como estas reglas de préstamo previenen errores de memoria, considera el caso de modificar una colección cuando existen referencias a sus elementos:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let elem = &vec[2];
    vec.push(6);
    println!("{elem}");
}

Considera este caso parecido de invalidación de iterador:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    for elem in &vec {
        vec.push(elem * 2);
    }
}

Mutabilidad Interior

En algunas situaciones, es necesario modificar los datos subyacentes a una referencia compartida (de solo lectura). Por ejemplo, una estructura de datos compartida puede contar con una caché interna y pretender actualizarla con métodos de solo lectura.

El patrón "mutabilidad interior" permite el acceso exclusivo (mutable) desde una referencia compartida. La biblioteca estándar ofrece varias formas de hacerlo y, al mismo tiempo, garantiza la seguridad, normalmente mediante una comprobación del tiempo de ejecución.

RefCell

use std::cell::RefCell;

fn main() {
    // Nota que `cell` NO es declarado como mutable.
    let cell = RefCell::new(5);

    {
        let mut cell_ref = cell.borrow_mut();
        *cell_ref = 123;

        // Esto causa un error al tiempo de ejecución.
        // let other = cell.borrow();
        // println!("{}", *other);
    }

    println!("{cell:?}");
}

Cell

Cell envuelve un valor y permite obtenerlo o definirlo, incluso con una referencia compartida a Cell. Sin embargo, no permite obtener referencias al valor. Como no hay referencias, las reglas de préstamos no pueden quebrantarse.

use std::cell::Cell;

fn main() {
    // Nota que `cell` NO es declarado como mutable.
    let cell = Cell::new(5);

    cell.set(123);
    println!("{}", cell.get());
}

Ejercicio: Estadísticas de Salud

Estás trabajando en la implementación de un sistema de monitorización de salud. Por ello, debes realizar un seguimiento de las estadísticas de salud de los usuarios.

Comenzarás con algunas funciones stub en un bloque impl, así como con una definición de estructura User. Tu objetivo es implementar métodos en el struct User definida en el bloque impl.

Copia el fragmento de código que aparece más abajo en la página a https://play.rust-lang.org/ y rellena el método que falta:

// TODO: borra esto cuando termines de implementarlo.
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!("Actualiza las estadísticas de un usuario en función de las mediciones obtenidas durante una consulta médica")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("Me llamo {} y tengo {} años", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

Solución

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("Me llamo {} y tengo {} años", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

Duraciones de vida

Esta sección tiene una duración aproximada de 50 minutos. Contiene:

Anotaciones de duración de vida

Una referencia tiene un valor de tiempo de vida que no debe "superar" el valor al que hace referencia. El verificador de préstamos se encarga de comprobarlo.

El tiempo de vida puede ser implícito, como hemos visto hasta ahora, pero también explícito, como es el caso de &'a Point y &'document str. Los tiempos de vida empiezan por ' y 'a es el nombre predeterminado que se suele usar. Lee &'a Point como "un Point prestado que es válido al menos durante el tiempo de vida a".

Los tiempos de vida siempre son inferidos por el compilador: no es posible asignar un tiempo de vida manualmente. Las anotaciones explicitas de tiempo de vida crean restricciones cuando hay ambigüedad; el compilador verifica que hay una solución válida.

Los tiempos de vida se vuelven más complejos cuando se tiene en cuenta la transferencia y devolución de valores a las funciones.

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // ¿Cuál es el tiempo de vida de p3?
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

Tiempos de Vida en Llamadas a Función

El tiempo de vida de los argumentos de las funciones y los valores devueltos se deben especificar de manera completa, pero Rust permite que se puedan eludir en la mayoría de los casos con unas reglas sencillas. Esto no es inferencia -- solo es un atajo de sintaxis.

• A cada argumento que no tenga una anotación de tiempo de vida se le proporciona uno.
• Si solo hay un tiempo de vida de un argumento, se le asigna a todos los valores devueltos que no estén anotados.
• Si existen varios tiempos de vida de argumentos, pero el primero es para self, ese tiempo de vida se asigna a todos los valores devueltos que no estén anotados.

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }
    nearest.map(|(p, _)| p)
}

fn main() {
    println!(
        "{:?}",
        nearest(
            &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1),],
            &Point(0, 2)
        )
    );
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

Tiempos de vida en estructuras de datos

Si un tipo de datos almacena datos prestados, se debe anotar con tiempo de vida:

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("¡Adiós, {text}!");
}

fn main() {
    let text = String::from("El veloz murciélago hindú comía feliz cardillo y kiwi. La cigüeña tocaba el saxofón detrás del palenque de paja.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

Ejercicio: Análisis de Protobuf

En este ejercicio, vas a compilar un analizador para la codificación binaria de protobuf. No hay nada de lo que preocuparse, es más sencillo de lo que parece. En este ejemplo se muestra un patrón de análisis muy habitual que consiste en transferir fracciones de datos. Los datos subyacentes nunca se copian.

Para poder llevar a cabo un análisis completo de un mensaje de protobuf, es necesario conocer los tipos de campos, indexados por el número de campo. Se suelen proporcionar en un archivo proto. En este ejercicio, codificaremos esa información en declaraciones match en funciones a las que se llama para cada campo.

Usaremos el proto que sigue:

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

Un mensaje proto se codifica como una serie de campos, uno detrás del otro. Cada uno se implementa como una "etiqueta" seguida del valor. La etiqueta contiene un número de campo (por ejemplo, 2 para el campo id de un mensaje de Person) y un tipo de wire que define cómo se debe definir la carga útil a partir del flujo de bytes.

Los números enteros, incluida la etiqueta, se representan con una codificación de longitud variable denominada VARINT. A continuación puedes consultar la definición de parse_varint. El código dado también define retrollamadas para gestionar los campos Person y PhoneNumber, así como analizar un mensaje en una serie de llamadas a dichas retrollamadas.

Ahora solo tienes que implementar la función parse_field y el trait ProtoMessage para Person y PhoneNumber.

/// Tipo de wire como se observa en el wire.
enum WireType {
    /// Varint WireType indica que el valor es un único VARINT.
    Varint,
    //I64,  -- no es necesario para este ejercicio
    /// El Len WireType indica que el valor es una longitud representada como
    /// VARINT seguida exactamente de ese número de bytes.
    Len,
    /// El WireType I32 indica que el valor es de 4 bytes en
    /// el orden little endian que contiene un número entero con signo de 32 bits.
    I32,
}

#[derive(Debug)]
/// Valor de un campo, escrito en función del tipo de wire.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- no es necesario para este ejercicio
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Campo que contiene el número de campo y su valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64, no es necesario para este ejercicio
            2 => WireType::Len,
            5 => WireType::I32,
            _ => panic!("Tipo de wire no válido: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Cadena era esperado ser un campo `Len`");
        };
        std::str::from_utf8(data).expect("Cadena no válida")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Bytes eran esperados ser un campo `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("`u64` era esperado ser un campo `Varint`");
        };
        *value
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("`i32` era esperado ser un campo `I32`");
        };
        *value
    }
}

/// Analiza un VARINT, que devuelve el valor analizado y los bytes restantes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("No hay suficientes bytes para un varint");
        };
        if b & 0x80 == 0 {
            // Este es el último byte de VARINT, así que conviértelo en
            // u64 y haz que lo devuelva.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Un número mayor de 7 bytes no es válido.
    panic!("Demasiados bytes para un varint");
}

/// Convierte una etiqueta en un número de campo y un WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}


/// Analiza un campo y haz que devuelva los bytes restantes.
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("En función del tipo de wire, crea un campo que utilice todos los bytes necesarios.")
    };
    todo!("Devuelve el campo y los bytes que no se hayan utilizado.")
}

/// Analiza un mensaje de los datos proporcionados, llamando a `T::add_field` para cada campo
/// del mensaje.
///
/// Se utilizan todos los datos introducidos.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TAREA: implementar ProtoMessage para Person y PhoneNumber.

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

Solución

/// Tipo de wire como se observa en el wire.
enum WireType {
    /// Varint WireType indica que el valor es un único VARINT.
    Varint,
    //I64,  -- no es necesario para este ejercicio
    /// El Len WireType indica que el valor es una longitud representada como
    /// VARINT seguida exactamente de ese número de bytes.
    Len,
    /// El WireType I32 indica que el valor es de 4 bytes en
    /// el orden little endian que contiene un número entero con signo de 32 bits.
    I32,
}

#[derive(Debug)]
/// Valor de un campo, escrito en función del tipo de wire.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- no es necesario para este ejercicio
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Campo que contiene el número de campo y su valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64, no es necesario para este ejercicio
            2 => WireType::Len,
            5 => WireType::I32,
            _ => panic!("Tipo de wire no válido: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Cadena era esperado ser un campo `Len`");
        };
        std::str::from_utf8(data).expect("Cadena no válida")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Bytes eran esperados ser un campo `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("`u64` era esperado ser un campo `Varint`");
        };
        *value
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("`i32` era esperado ser un campo `I32`");
        };
        *value
    }
}

/// Analiza un VARINT, que devuelve el valor analizado y los bytes restantes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("No hay suficientes bytes para un varint");
        };
        if b & 0x80 == 0 {
            // Este es el último byte de VARINT, así que conviértelo en
            // u64 y haz que lo devuelva.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Un número mayor de 7 bytes no es válido.
    panic!("Demasiados bytes para un varint");
}

/// Convierte una etiqueta en un número de campo y un WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}

/// Analiza un campo y haz que devuelva los bytes restantes.
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder);
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder);
            let len: usize = len.try_into().expect("len no es un `usize` valido");
            if remainder.len() < len {
                panic!("EOF inesperado");
            }
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
        WireType::I32 => {
            if remainder.len() < 4 {
                panic!("EOF inesperado");
            }
            let (value, remainder) = remainder.split_at(4);
            // Desenvuelve el error porque `value` tiene 4 bytes.
            let value = i32::from_le_bytes(value.try_into().unwrap());
            (FieldValue::I32(value), remainder)
        }
    };
    (Field { field_num, value: fieldvalue }, remainder)
}

/// Analiza un mensaje de los datos proporcionados, llamando a `T::add_field` para cada campo
/// del mensaje.
///
/// Se utilizan todos los datos introducidos.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.name = field.value.as_string(),
            2 => self.id = field.value.as_u64(),
            3 => self.phone.push(parse_message(field.value.as_bytes())),
            _ => {} // salta todos los demás pasos
        }
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.number = field.value.as_string(),
            2 => self.type_ = field.value.as_string(),
            _ => {} // salta todos los demás pasos
        }
    }
}

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

Bienvenido al Día 4

Hoy vamos a tratar algunos temas relacionados con la construcción de aplicaciones de grande escala en Rust:

• Iteradores: información detallada sobre el trait Iterator.
• Módulos y visibilidad.
• Probando.
• Gestión de errores: panics (pánicos), Result y el operador try ?.
• Rust inseguro: una vía de escape en las situaciones en las que no puedes expresarte en Rust seguro.

Horario

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 40 minutos. Contiene:

Iteradores

Esta sección tiene una duración aproximada de 45 minutos. Contiene:

Iterator

El trait Iterator permite iterar valores en una colección. Requiere un método next y proporciona muchos otros métodos. Muchos tipos de bibliotecas estándar implementan Iterator y también está a nuestro alcance:

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

El trait Iterator te indica cómo iterar una vez que has creado un iterador. El trait relacionado IntoIterator indica cómo crear un iterador para un tipo. Es usado automáticamente por los bucles for.

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };
    for (x, y) in grid {
        println!("punto = {x}, {y}");
    }
}

FromIterator

FromIterator permite construir una colección a partir de un Iterator.

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

Ejercicio: Encadenamiento de métodos del iterador

En este ejercicio, necesitaras encontrar y usar métodos del trait Iterator para implementar una calculación compleja.

Copia el siguiente fragmento de código en la página https://play.rust-lang.org/ y haz que las pruebas sucedan sin error. Usa una expresión de iterador y collect para construir el valor devuelto.

#![allow(unused)]
fn main() {
/// Calcula las diferencias entre los elementos de `values` offset por offset,
/// envolviendo de esta forma los elementos desde el final de `values` hasta el principio.
///
/// El elemento `n` del resultado es `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    unimplemented!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}
}

Solución

/// Calcula las diferencias entre los elementos de `values` offset por offset,
/// envolviendo de esta forma los elementos desde el final de `values` hasta el principio.
///
/// El elemento `n` del resultado es `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    let a = (&values).into_iter();
    let b = (&values).into_iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

fn main() {}

Módulos

Esta sección tiene una duración aproximada de 40 minutos y contiene:

Módulos

Hemos visto cómo los bloques impl nos permiten asignar espacios de nombres de funciones a un tipo.

Del mismo modo, mod nos permite asignar espacios de nombres a funciones y tipos:

mod foo {
    pub fn do_something() {
        println!("En el módulo foo");
    }
}

mod bar {
    pub fn do_something() {
        println!("En el módulo bar");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

Jerarquía del sistema de archivos

Omitir el contenido del módulo hará que Rust lo busque en otro archivo:

mod garden;

Esto indica que el contenido del módulo garden se encuentra en src/garden.rs. Del mismo modo, el módulo garden::vegetables se encuentra en src/garden/vegetables.rs.

La raíz de crate está en:

• src/lib.rs (para un crate de biblioteca)
• src/main.rs (para un crate binario)

Los módulos definidos en archivos también se pueden documentar mediante "comentarios internos del documento". En ellos se indica el elemento que los contiene, en este caso, un módulo.

//! Este módulo implementa el jardín, incluida una germinación de alto rendimiento.
//!

// Vuelve a exportar los tipos de este módulo.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Siembra los paquetes de semilla determinados.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Cosecha el producto en el jardín que esté listo.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

Visibilidad

Los módulos marcan el límite de la privacidad:

• Los elementos del módulo son privados de forma predeterminada (se ocultan los detalles de implementación).
• Los elementos superiores y los del mismo nivel siempre están visibles.
• Es decir, si un elemento está visible en el módulo foo, se verá en todos los elementos descendientes de foo.

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

use, super, self

Un módulo puede incluir símbolos de otro módulo en el ámbito con use. Normalmente, se ve algo como esto en la parte superior de cada módulo:

use std::collections::HashSet;
use std::process::abort;

Rutas

Las rutas se resuelven de la siguiente manera:

1. Como ruta relativa:

   • foo o self::foo hacen referencia a foo en el módulo corriente,
   • super::foo hace referencia a foo en el módulo superior.

2. Como ruta absoluta:

   • crate::foo hace referencia a foo en la raíz del crate corriente,
   • bar::foo hace referencia a foo en el crate bar.

Ejercicio: Módulos para una biblioteca GUI

En este ejercicio, vas a reorganizar una pequeña implementación de una biblioteca GUI. Esta biblioteca define un trait Widget y algunas implementaciones de dicho trait, así como una función main.

Es habitual colocar cada tipo o conjunto de tipos que estén estrechamente relacionados en su propio módulo, por lo que cada tipo de widget debe tener su propio módulo.

Configuración de Cargo

El playground de Rust solo admite un archivo, por lo que tendrás que crear un proyecto de Cargo en tu sistema de archivos local:

cargo init gui-modules
cd gui-modules
cargo run

Edita el archivo src/main.rs resultante para añadir instrucciones mod y añade archivos adicionales en el directorio src.

Fuente

A continuación, se muestra la implementación de la biblioteca GUI en un solo módulo:

pub trait Widget {
    /// Ancho natural de `self`.
    fn width(&self) -> usize;

    /// Coloca el widget en un búfer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Coloca el widget en una salida estándar.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // Añade 4 espacios de relleno para los bordes
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TAREAS: Cambia draw_into para devolver Result<(), std::fmt::Error>. A continuación, utiliza el
        // operator ? en lugar de .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // añade un poco de espacio de relleno
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Demo de la GUI de Rust 1.23");
    window.add_widget(Box::new(Label::new("Esta es una demo de la GUI con poco texto.")));
    window.add_widget(Box::new(Button::new("Haz clic aquí")));
    window.draw();
}

Solución

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// Ancho natural de `self`.
    fn width(&self) -> usize;

    /// Coloca el widget en un búfer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Coloca el widget en una salida estándar.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // añade un poco de espacio de relleno
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: window-width
        // Añade 4 espacios de relleno para los bordes
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TAREA: después de saber cómo gestionar los errores, puedes cambiar
        // draw_into para devolver Result<(), std::fmt::Error>. A continuación, usa
        // el operator ? en lugar de .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Demo de la GUI de Rust 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("Esta es una demo de la GUI con poco texto.")));
    window.add_widget(Box::new(widgets::Button::new("Haz clic aquí")));
    window.draw();
}

Probando

Esta sección tiene una duración aproximada de 45 minutos. Contiene:

Pruebas Unitarias

Rust y Cargo incluyen un sencillo framework para pruebas unitarias:

• Las pruebas unitarias se admiten en todo el código.

• Las pruebas de integración se admiten a través del directorio tests/.

Las pruebas se marcan con #[test]. Las pruebas unitarias se suelen incluir en un módulo tests anidado en el que se utiliza #[cfg(test)] para compilarlas únicamente cuando se compilan las pruebas.

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty() {
        assert_eq!(first_word(""), "");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("Hola"), "Hola");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Hola, mundo"), "Hola");
    }
}

• Esto permite realizar pruebas unitarias de los ayudantes privados.
• El atributo #[cfg(test)] solo está activo cuando se ejecuta cargo test.

Otros tipos de pruebas

Pruebas de Integración

Si quieres probar tu biblioteca como cliente, haz una prueba de integración.

Crea un archivo .rs en tests/:

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

Estas pruebas solo tienen acceso a la API pública de tu crate.

Pruebas de Documentación

Rust cuenta con asistencia integrada para pruebas de documentación:

#![allow(unused)]
fn main() {
/// Acorta una cadena según la longitud proporcionada.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hola, mundo", 5), "Hola");
/// assert_eq!(shorten_string("Hola, mundo", 20), "Hola, mundo");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• Los bloques de código en los comentarios /// se ven automáticamente como código de Rust.
• El código se compilará y ejecutará como parte de cargo test.
• Si añades # al código, se ocultará de los documentos, pero se seguirá compilando o ejecutando.
• Prueba el código anterior en el playground de Rust.

Lints de compiladores y Clippy

El compilador de Rust crea mensajes de error muy buenos, así como lints integrados útiles. Clippy ofrece aún más lints, organizados en grupos que se pueden habilitar por proyecto.

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("Es probable que X encaje en una u16, ¿no? {}", x as u16);
}

Ejercicio: Algoritmo de Luhn

Algoritmo de Luhn

El algoritmo de Luhn se usa para validar números de tarjetas de crédito. El algoritmo toma una cadena como entrada y hace lo siguiente para validar el número de la tarjeta de crédito:

• Ignora todos los espacios. Rechaza los números con menos de dos dígitos.

• De derecha a izquierda, duplica cada dos cifras: en el caso del número 1234, se duplica el 3 y el 1. En el caso del número 98765, se duplica el 6 y el 8.

• Después de duplicar un dígito, se suman los dígitos si el resultado es mayor a 9. Por tanto, si duplicas 7, pasará a ser 14, lo cual pasará a ser 1 +4 = 5.

• Suma todos los dígitos, no duplicados y duplicados.

• El número de la tarjeta de crédito es válido si la suma termina en 0.

El código proporcionado ofrece una implementación errónea del algoritmo de Luhn, junto con dos pruebas unitarias básicas que confirman que la mayor parte del algoritmo se ha implementado correctamente.

Copia el fragmento de código que aparece más abajo en la página a https://play.rust-lang.org/ y escribe pruebas adicionales para descubrir y arreglar errores en la implementación proveída.

#![allow(unused)]
fn main() {
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}
}

Solución

// Esta es la versión con errores que aparece en el problema.
#[cfg(never)]
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

// Esta es la solución, que pasará todas las siguientes pruebas.
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            continue;
        } else {
            return false;
        }
    }

    digits >= 2 && sum % 10 == 0
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "¿Es {cc_number} un número de tarjeta de crédito válido? {}",
        if luhn(cc_number) { "sí" } else { "no" }
    );
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0"));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn(""));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

Te damos la bienvenida

Contando con los descansos de 10 minutos, la duración prevista de la sesión es de unas 2 horas y 15 minutos. Contiene:

Manejo de Errores

Esta sección tiene una duración aproximada de 1 hora. Contiene:

Pánicos

Rust gestiona los errores críticos con un "pánico".

Rust activará un panic si se produce un error grave en runtime:

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• Los panics se usan para errores irrecuperables e inesperados.
  • Los panics son un síntoma de que hay fallos en el programa.
  • Los fallos del tiempo de ejecución, como las comprobaciones de límites fallidas, pueden causar un pánico
  • Las aserciones (como assert!) causan un pánico cuando fallan
  • Los pánicos con fines específicos pueden usar la macro panic!.
• Cuando se produce un pánico, se "desenrolla" la pila y se eliminan los valores como si las funciones hubieran devuelto un resultado.
• Utiliza API que no activen panics (como Vec::get) si no se admiten fallos.

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "No hay ningún problema.");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("¡Vaya!");
    });
    println!("{result:?}");
}

Result

El mecanismo primario para el manejo de errores en Rust es el enum Result, que vimos brevemente al discutir los tipos de la biblioteca estándar.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Querido diario: {contents} ({bytes} bytes)");
            } else {
                println!("No se ha podido leer el contenido del archivo");
            }
        }
        Err(err) => {
            println!("No se ha podido abrir el diario: {err}");
        }
    }
}

Operador Try (Intentar)

Los errores de tiempo de ejecución, como los de fallo en la conexión o de archivo no encontrado, se gestionan con el tipo Result, pero hacer coincidir este tipo en todas las llamadas puede ser complicado. El operador try ? se utiliza para devolver errores al llamador. Te permite convertir lo habitual

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

en algo mucho más sencillo:

some_expression?

Podemos utilizarlo para simplificar el código de gestión de errores:

use std::io::Read;
use std::{fs, io};

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("nombre de usuario o error: {username:?}");
}

Conversiones Try (Intentar)

La expansión efectiva de ? es un poco más complicada de lo que se ha indicado anteriormente:

expression?

funciona igual que

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

The From::from call here means we attempt to convert the error type to the type returned by the function. This makes it easy to encapsulate errors into higher-level errors.

Ejemplo

use std::error::Error;
use std::fmt::{self, Display, Formatter};
use std::fs::File;
use std::io::{self, Read};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl Display for ReadUsernameError {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "Error IO: {e}"),
            Self::EmptyUsername(path) => write!(f, "No se ha encontrado ningún nombre de usuario en {path}"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //std::fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("nombre de usuario o error: {username:?}");
}

Tipos de Errores Dinámicos

Sometimes we want to allow any type of error to be returned without writing our own enum covering all the different possibilities. The std::error::Error trait makes it easy to create a trait object that can contain any error.

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("Recuento: {count}"),
        Err(err) => println!("Error: {err}"),
    }
}

thiserror y anyhow

The thiserror and anyhow crates are widely used to simplify error handling.

• thiserror se suele usar en bibliotecas para crear tipos de errores personalizados que implementan From<T>.
• Las aplicaciones suelen utilizar anyhow para gestionar errores en funciones, como añadir información contextual a los errores.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("No se ha encontrado ningún nombre de usuario en {0}")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("No se ha podido abrir {path}"))?
        .read_to_string(&mut username)
        .context("No se ha podido leer")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Nombre de usuario: {username}"),
        Err(err) => println!("Error: {err:?}"),
    }
}

Ejercicio: Reescribir con Result

A continuación, se implementa un analizador muy sencillo para un lenguaje de expresiones. Sin embargo, para gestionar los errores, utiliza pánicos. Reescribe este texto para utilizar la gestión de errores idiomática y propagar los errores a un instrucción de retorno desde main. No dudes en usar thiserror y anyhow.

CONSEJO: empieza por corregir la gestión de errores en la función parse. Cuando funcione correctamente, actualiza Tokenizer para implementar Iterator<Item=Result<Token, TokenizerError>> y gestiónalo en el analizador.

use std::iter::Peekable;
use std::str::Chars;

/// Un operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Un token en el lenguaje expresión.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Una expresión en el lenguaje de la expresión.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Una referencia a una variable.
    Var(String),
    /// Un número literal.
    Number(u32),
    /// Una operación binaria.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(self.collect_number(c)),
            'a'..='z' => Some(self.collect_identifier(c)),
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("Carácter inesperado {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("Fin de entrada inesperado");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Número entero de 32 bits no válido'");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Token inesperado: {tok:?}"),
        };
        // Analiza la operación binaria, si procede.
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("Token inesperado: {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

Solución

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// Un operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Un token en el lenguaje expresión.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Una expresión en el lenguaje de la expresión.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Una referencia a una variable.
    Var(String),
    /// Un número literal.
    Number(u32),
    /// Una operación binaria.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Carácter inesperado '{0}' en la entrada")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(Ok(self.collect_number(c))),
            'a'..='z' | '_' => Some(Ok(self.collect_identifier(c))),
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("Error del tokenizador: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Fin de entrada inesperado")]
    UnexpectedEOF,
    #[error("Token inesperado: {0:?}")]
    UnexpectedToken(Token),
    #[error("Número no válido")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // Analiza la operación binaria, si procede.
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

Unsafe Rust

This segment should take about 1 hour and 5 minutes. It contains:

Unsafe Rust

El lenguaje Rust tiene dos partes:

• Safe Rust: memoria segura, sin posibilidad de comportamiento indefinido.
• Unsafe Rust: puede activar un comportamiento no definido si se infringen las condiciones previas.

We saw mostly safe Rust in this course, but it's important to know what Unsafe Rust is.

Por lo general, el código inseguro es pequeño y está aislado, y su corrección debe estar bien documentada. Suele estar envuelto en una capa de abstracción segura.

Rust inseguro te permite acceder a cinco nuevas funciones:

• Desreferenciar punteros sin formato.
• Acceder o modificar variables estáticas mutables.
• Acceder a los campos union.
• Llamar a funciones unsafe, incluidas las funciones extern.
• Implementar traits unsafe.

A continuación, hablaremos brevemente sobre las funciones que no son seguras. Para obtener más información, consulta el capítulo 19.1 del Libro de Rust y el documento Rustonomicon.

Dereferenciación de Punteros Sin Formato

La creación de punteros es un proceso seguro, pero para anular las referencias, es necesario utilizar unsafe:

fn main() {
    let mut s = String::from("¡cuidado!");

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // SAFETY: r1 and r2 were obtained from references and so are guaranteed to
    // be non-null and properly aligned, the objects underlying the references
    // from which they were obtained are live throughout the whole unsafe
    // block, and they are not accessed either through the references or
    // concurrently through any other pointers.
    unsafe {
        println!("r1 es: {}", *r1);
        *r1 = String::from("oh, oh");
        println!("r2 es: {}", *r2);
    }

    // NO ES SEGURO. NO HAGAS ESTO.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 is: {}", *r3);
    */
}

Variables Estáticas Mutables

Es seguro leer una variable estática inmutable:

static HELLO_WORLD: &str = "¡Hola, mundo!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

Sin embargo, dado que pueden producirse carreras de datos, no es seguro leer y escribir variables estáticas mutables:

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        println!("CONTADOR: {COUNTER}");
    }
}

Uniones

Las uniones son como enums (enumeraciones), pero eres tú quien debe hacer el seguimiento del campo activo:

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // ¡Comportamiento indefinido!
}

Funciones Inseguras (Unsafe)

Llamar Funciones Unsafe (Inseguras)

Una función o método se puede marcar como unsafe si tiene condiciones previas adicionales que debes mantener para evitar un comportamiento indefinido:

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // SAFETY: The indices are in the correct order, within the bounds of the
    // string slice, and lie on UTF-8 sequence boundaries.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("recuento de caracteres: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    // SAFETY: `abs` doesn't deal with pointers and doesn't have any safety
    // requirements.
    unsafe {
        println!("Valor absoluto de -3 según C: {}", abs(-3));
    }

    // Si no se mantiene el requisito de codificación UTF-8, se verá afectada la seguridad de la memoria.
    // println!("emoji: {}", no seguro { emojis.get_unchecked(0..3) });
    // println!("recuento de caracteres: {}", count_chars(no seguro {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

Escribir Funciones Unsafe (Inseguras)

Puedes marcar tus propias funciones como unsafe si requieren condiciones concretas para evitar un comportamiento indefinido.

/// Cambia los valores a los que apuntan los punteros proporcionados.
///
/// # Seguridad
///
/// Los punteros deben ser válidos y estar alineados adecuadamente.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // SAFETY: ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Implementación de Traits Unsafe (Inseguras)

Al igual que con las funciones, puedes marcar un trait como unsafe si la implementación debe asegurar condiciones concretas para evitar un comportamiento indefinido.

Por ejemplo, el crate zerocopy tiene un trait inseguro, que se parece a esto:

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Seguridad
/// El tipo debe tener una representación definida y no tener espacio de relleno.
pub unsafe trait AsBytes {
    fn as_bytes(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(
                self as *const Self as *const u8,
                size_of_val(self),
            )
        }
    }
}

// SAFETY: `u32` has a defined representation and no padding.
unsafe impl AsBytes for u32 {}

Envoltorio de FFI Seguro

Rust ofrece una gran asisencia para llamar a funciones a través de una interfaz de función externa (FFI). Usaremos esto para crear un envoltorio seguro para las funciones libc que usarías desde C para leer los nombres de archivo de un directorio.

Consulta las páginas del manual:

• opendir(3)
• readdir(3)
• closedir(3)

También te recomendamos que consultes el módulo std::ffi. Ahí encontrarás una serie de tipos de cadena que necesitas para el ejercicio:

Realizarás conversiones entre todos estos tipos:

• De &str a CString: debes asignar espacio para un carácter final \0,
• De CString a *const i8: necesitas un puntero para llamar a funciones C,
• De *const i8 a &CStr: necesitas algo que pueda encontrar el carácter final \0,
• &CStr to &[u8]: a slice of bytes is the universal interface for "some unknown data",
• De &[u8] a &OsStr: &OsStr es un paso hacia OsString, usa OsStrExt para crearlo.
• De OsStr a OsString: debes clonar los datos en &OsStr para poder devolverlo y llamar a readdir de nuevo.

El Nomicon también tiene un capítulo muy útil sobre FFI.

Copia el fragmento de código que aparece más abajo en la página https://play.rust-lang.org/ y rellena los métodos y funciones que faltan:

// TODO: borra esto cuando termines de implementarlo.
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Tipo opaco. Consulta https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Diseño según la página del manual de Linux para readdir(3), donde ino_t y
    // off_t se resuelven de acuerdo con las definiciones de
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}. .
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Diseño según la página del manual de macOS de dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Consulta https://github.com/rust-lang/libc/issues/414 y la sección sobre
 // _DARWIN_FEATURE_64_BIT_INODE en la página del manual de macOS de stat(2).
 //
 // " Las plataformas que existían antes de que estas actualizaciones estuvieran disponibles" hacen referencia
 // a macOS (en lugar de iOS, WearOS, etc.) en Intel y PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Llama a opendir y devuelve un valor Ok si ha funcionado,
        // de lo contrario, devuelve Err con un mensaje.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Sigue llamando a readdir hasta se obtenga un puntero NULL.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Llama a closedir según sea necesario.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("archivos: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

Solución

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Tipo opaco. Consulta https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Diseño según la página del manual de Linux para readdir(3), donde ino_t y
    // off_t se resuelven de acuerdo con las definiciones de
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}. .
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Diseño según la página del manual de macOS de dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Consulta https://github.com/rust-lang/libc/issues/414 y la sección sobre
 // _DARWIN_FEATURE_64_BIT_INODE en la página del manual de macOS de stat(2).
 //
 // " Las plataformas que existían antes de que estas actualizaciones estuvieran disponibles" hacen referencia
 // a macOS (en lugar de iOS, WearOS, etc.) en Intel y PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Llama a opendir y devuelve un valor Ok si ha funcionado,
        // de lo contrario, devuelve Err con un mensaje.
        let path =
            CString::new(path).map_err(|err| format!("Ruta no válida: {err}"))?;
        // SEGURIDAD: path.as_ptr() no puede ser NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("No se ha podido abrir {:?}", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Sigue llamando a readdir hasta que se obtenga un puntero NULL.
        // SEGURIDAD: self.dir nunca es NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // Hemos llegado al final del directorio.
            return None;
        }
        // SEGURIDAD: dirent no es NULL y dirent.d_name es NULL
        // finalizado.
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Llama a closedir según sea necesario.
        if !self.dir.is_null() {
            // SEGURIDAD: self.dir no es NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("No se ha podido cerrar {:?}.", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("archivos: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("no-such-directory");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Hay un carácter no codificado en UTF-8 en la ruta")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "The Foo Diaries\n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Crab\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Hay un carácter no codificado en UTF-8 en la ruta")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

Te Damos la Bienvenida a Rust en Android

Rust is supported for system software on Android. This means that you can write new services, libraries, drivers or even firmware in Rust (or improve existing code as needed).

Hoy intentaremos llamar a Rust desde un proyecto personal. Intenta encontrar una pequeña esquina de tu código base donde podamos mover algunas líneas de código a Rust. Cuantas menos dependencias y tipos "exóticos" tenga, mejor. Lo ideal sería algo que analizara bytes sin procesar.

Configurar

We will be using a Cuttlefish Android Virtual Device to test our code. Make sure you have access to one or create a new one with:

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

Consulta el Codelab para desarrolladores de Android para obtener más información.

Reglas de Compilación (Build)

El sistema de compilación de Android (Soong) es compatible con Rust a través de una serie de módulos:

A continuación, hablaremos de rust_binary y rust_library.

Binarios de Rust

Empecemos con una sencilla aplicación. Desde la raíz de un AOSP revisado, crea los siguientes archivos:

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Demo de Rust.

/// Imprime un saludo en una salida estándar.
fn main() {
    println!("¡Saludos de parte Rust!");
}

Ahora puedes compilar, insertar y ejecutar el binario:

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust" /data/local/tmp
adb shell /data/local/tmp/hello_rust

Hello from Rust!

Bibliotecas de Rust

Crea una biblioteca de Rust para Android con rust_library.

Aquí declaramos una dependencia en dos bibliotecas:

• libgreeting, que definimos más abajo.
• libtextwrap, que es un crate ya incluido en external/rust/crates/.

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // Es necesario para evitar errores de enlace dinámico.
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Demo de Rust.

use greetings::greeting;
use textwrap::fill;

/// Imprime un saludo en una salida estándar.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! Biblioteca de saludos.

/// Saluda a `name`.
pub fn greeting(name: &str) -> String {
    format!("Hello {name}, it is very nice to meet you!")
}

Puedes compilar, insertar y ejecutar el binario como antes:

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep" /data/local/tmp
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL

El lenguaje de definición de la interfaz de Android (AIDL) es compatible con Rust:

• El código de Rust puede llamar a servidores AIDL que ya se hayan creado.
• Puedes crear servidores de AIDL en Rust.

Tutorial de Servicio de Cumpleaños

To illustrate how to use Rust with Binder, we're going to walk through the process of creating a Binder interface. We're then going to both implement the described service and write client code that talks to that service.

Interfaces de AIDL

La API de tu servicio se declara mediante una interfaz de AIDL:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp:

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust no está habilitado de forma predeterminada
            enabled: true,
        },
    },
}

Generated Service API

Binder generates a trait corresponding to the interface definition. trait to talk to the service.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

Generated trait:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Your service will need to implement this trait, and your client will use this trait to talk to the service.

Implementación del servicio

Ahora podemos implementar el servicio de AIDL:

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// The `IBirthdayService` implementation.
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("Feliz cumpleaños, {name}, te han caído {years} años".))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

Servidor de AIDL

Por último, podemos crear un servidor que exponga el servicio:

birthday_service/src/server.rs:

//! Servicio de felicitación cumpleaños.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Punto de entrada del servicio de felicitación cumpleaños.
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("No se ha podido registrar el servicio");
    binder::ProcessState::join_thread_pool()
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // Para evitar errores de enlaces dinámicos.
}

Despliegue

Ahora podemos crear, insertar e iniciar el servicio:

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server" /data/local/tmp
adb root
adb shell /data/local/tmp/birthday_server

Comprueba que el servicio funciona en otra terminal:

adb shell service check birthdayservice

Service birthdayservice: found

También puedes llamar al servicio con service call:

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

Cliente de AIDL

Por último, podemos crear un cliente de Rust para nuestro nuevo servicio.

birthday_service/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Llama al servicio de felicitación cumpleaños.
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "No se ha podido conectar con el servicio de felicitación de cumpleaños.")?;

    // Call the service.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // Para evitar errores de enlaces dinámicos.
}

Ten en cuenta que el cliente no depende de libbirthdayservice.

Compila, inserta y ejecuta el cliente en tu dispositivo:

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

Cambio de API

Ampliemos la API con más funciones. Queremos que los clientes puedan indicar una lista de líneas para la tarjeta de cumpleaños:

package com.example.birthdayservice;

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

This results in an updated trait definition for IBirthdayService:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Updating Client and Service

Update the client and server code to account for the new API.

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "Feliz cumpleaños, {name}, te han caído {years} años".,
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_service/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("And also: many more"),
    ],
)?;

Working With AIDL Types

AIDL types translate into the appropriate idiomatic Rust type:

• Primitive types map (mostly) to idiomatic Rust types.
• Collection types like slices, Vecs and string types are supported.
• References to AIDL objects and file handles can be sent between clients and services.
• File handles and parcelables are fully supported.

Tipos Primitivos

Primitive types map (mostly) idiomatically:

Tipos Array

The array types (T[], byte[], and List<T>) get translated to the appropriate Rust array type depending on how they are used in the function signature:

Enviando Objectos

AIDL objects can be sent either as a concrete AIDL type or as the type-erased IBinder interface:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** The same thing, but using a binder object. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** The same thing, but using `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust struct implementing the `IBirthdayInfoProvider` interface.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("No se ha podido conectar con el servicio de felicitación de cumpleaños.");

    // Create a binder object for the `IBirthdayInfoProvider` interface.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Send the binder object to the service.
    service.wishWithProvider(&provider)?;

    // Perform the same operation but passing the provider as an `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

Variables

Binder for Rust supports sending parcelables directly:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** The same thing, but with a parcelable. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("No se ha podido conectar con el servicio de felicitación de cumpleaños.");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

Enviando Archívos

Files can be sent between Binder clients/servers using the ParcelFileDescriptor type:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** The same thing, but loads info from a file. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("No se ha podido conectar con el servicio de felicitación de cumpleaños.");

    // Open a file and put the birthday info in it.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Create a `ParcelFileDescriptor` from the file and send it.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
        // an `OwnedFd`, which can be cloned and then used to create a `File`
        // object.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Invalid file handle");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("Feliz cumpleaños, {name}, te han caído {years} años".))
    }
}

Testing in Android

Building on Testing, we will now look at how unit tests work in AOSP. Use the rust_test module for your unit tests:

testing/Android.bp:

rust_library {
    name: "libleftpad",
    crate_name: "leftpad",
    srcs: ["src/lib.rs"],
}

rust_test {
    name: "libleftpad_test",
    crate_name: "leftpad_test",
    srcs: ["src/lib.rs"],
    host_supported: true,
    test_suites: ["general-tests"],
}

testing/src/lib.rs:

#![allow(unused)]
fn main() {
//! Left-padding library.

/// Left-pad `s` to `width`.
pub fn leftpad(s: &str, width: usize) -> String {
    format!("{s:>width$}")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn short_string() {
        assert_eq!(leftpad("foo", 5), "  foo");
    }

    #[test]
    fn long_string() {
        assert_eq!(leftpad("foobar", 6), "foobar");
    }
}
}

You can now run the test with

atest --host libleftpad_test

The output looks like this:

INFO: Elapsed time: 2.666s, Critical Path: 2.40s
INFO: 3 processes: 2 internal, 1 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//comprehensive-rust-android/testing:libleftpad_test_host            PASSED in 2.3s
    PASSED  libleftpad_test.tests::long_string (0.0s)
    PASSED  libleftpad_test.tests::short_string (0.0s)
Test cases: finished with 2 passing and 0 failing out of 2 test cases

Notice how you only mention the root of the library crate. Tests are found recursively in nested modules.

GoogleTest

The GoogleTest crate allows for flexible test assertions using matchers:

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq("foo"), lt("xyz"), starts_with("b")));
}

Si cambiamos el último elemento a "!", la prueba dará error y aparecerá un mensaje de error estructurado que señala cuál es el fallo:

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Se ha encontrado la seguridad de la memoria,\n\
 la potente escritura de Rust guía el camino,\n\
 protege el código que vayas a escribir.";
    assert_that!(
        haiku,
        eq("Se ha encontrado seguridad en la memoria,\n\
 el divertido sentido del humor de Rust guía el camino,\n\
 protege el código que vayas a escribir.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

Simulaciones

Mockall es una biblioteca que se usa para hacer simulaciones. Debes refactorizar tu código para usar traits, con los que podrás hacer simulaciones:

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

Almacenamiento de registros

Utiliza el crate log para que se registre automáticamente en logcat (en el dispositivo) o stdout (en el host):

hello_rust_logs/Android.bp:

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs:

//! Demo de registros de Rust.

use log::{debug, error, info};

/// Registra un saludo.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("Iniciando programa.");
    info!("Todo es correcto.");
    error!("Se ha producido un error.");
}

Compila, inserta y ejecuta el binario en tu dispositivo:

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs" /data/local/tmp
adb shell /data/local/tmp/hello_rust_logs

Los registros se muestran en adb logcat:

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

Interoperabilidad

Rust admite sin problemas la interoperabilidad con otros lenguajes. Esto significa que puedes hacer lo siguiente:

• Llamar a funciones de Rust desde otros lenguajes.
• Llamar a funciones escritas en otros lenguajes desde Rust.

Cuando llamas a funciones en otro lenguaje, se dice que estás usando una interfaz de función externa, también denominada FFI.

Interoperabilidad con C

Rust admite vincular archivos de objetos con una convención de llamada de C. Del mismo modo, puedes exportar funciones de Rust y llamarlas desde C.

Si quieres, puedes hacerlo de forma manual:

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    // SAFETY: `abs` doesn't have any safety requirements.
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

Ya lo hemos visto en el ejercicio Envoltorio de FFI seguro.

Esto supone un conocimiento completo de la plataforma objetivo. No se recomienda para producción.

A continuación, estudiaremos otras opciones mejores.

Uso de Bindgen

La herramienta bindgen puede generar automáticamente enlaces desde un archivo de encabezado de C.

En primer lugar, crea una biblioteca de C pequeña:

interoperability/bindgen/libbirthday.h:

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

interoperability/bindgen/libbirthday.c:

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("| ¡Feliz cumpleaños, %s!\n", card->name);
  printf("| ¡Enhorabuena por cumplir %i años!\n", card->years);
  printf("+--------------\n");
}

Añade lo siguiente a tu archivo Android.bp:

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

Crea un archivo de encabezado de envoltorio para la biblioteca (no es estrictamente necesario en este ejemplo):

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

Ahora puedes generar automáticamente los enlaces:

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

Por último, podemos utilizar los enlaces de nuestro programa de Rust:

interoperability/bindgen/Android.bp:

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Demo de Bindgen.

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("Peter").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // SAFETY: The pointer we pass is valid because it came from a Rust
    // reference, and the `name` it contains refers to `name` above which also
    // remains valid. `print_card` doesn't store either pointer to use later
    // after it returns.
    unsafe {
        print_card(&card as *const card);
    }
}

Compila, inserta y ejecuta el binario en tu dispositivo:

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card" /data/local/tmp
adb shell /data/local/tmp/print_birthday_card

Por último, podemos ejecutar pruebas generadas automáticamente para comprobar que los enlaces funcionan:

interoperability/bindgen/Android.bp:

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "ninguno", // Archivo generado, se omite la ejecución de lint
    lints: "ninguno",
}

atest libbirthday_bindgen_test

Llamar a Rust

Es fácil exportar las funciones y los tipos de Rust a C:

interoperability/rust/libanalyze/analyze.rs

//! Demo de FFI de Rust.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analiza los números.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("¡x ({x}) es el menor!");
    } else {
        println!("y ({y}) probablemente sea mayor que x ({x})");
    }
}

interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

extern "C" {
void analyze_numbers(int x, int y);
}

#endif

interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

Ahora podemos llamarlo desde un binario de C:

interoperability/rust/analyze/main.c

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

Compila, inserta y ejecuta el binario en tu dispositivo:

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers" /data/local/tmp
adb shell /data/local/tmp/analyze_numbers

Con C++

El crate CXX permite una interoperabilidad segura entre Rust y C++.

El enfoque general es el siguiente:

El Modulo Puente (Bridge)

CXX se basa en una descripción de las firmas de la función que se mostrarán de un lenguaje a otro. Proporcionas esta descripción mediante bloques externos en un módulo de Rust anotado con la macro de atributo #[cxx::bridge].

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Estructuras compartidas con campos visibles para ambos lenguajes.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Tipos y firmas de Rust expuestos a C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // Tipos y firmas de C++ y expuestos a Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Declaraciones Bridge en Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Tipo opaco
        fn foo(&self); // Método en `MyType`
        fn bar() -> Box<MyType>; // Free function
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

C++ generado

#[cxx::bridge]
mod ffi {
    // Tipos y firmas de Rust expuestos a C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

Los resultados son (aproximadamente) los que se muestran a continuación en C++:

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

Declaraciones Bridge en C++

#[cxx::bridge]
mod ffi {
    // Tipos y firmas de C++ y expuestos a Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Los resultados son (aproximadamente) los que se muestran a continuación en Rust:

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

Tipos de datos compartidos

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Enums compartidos

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Rust generado:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

C++ generado:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

Manejo de Errores en Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 requiere una profundidad > 0"));
    }

    Ok("Correcto.".into())
}

Manejo de Errores en C++

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Error: {}", err);
        process::exit(1);
    }
}

Tipos adicionales

Building in Android

Crea un cc_library_static para compilar la biblioteca de C++, incluidos el encabezado y el archivo de origen generados por CXX.

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

Building in Android

Crea dos genrule, una para generar el encabezado de CXX y otra para generar el archivo de origen de CXX. Luego se usarán como entradas a cc_library_static.

// Genera un encabezado de C++ que contenga los enlaces de C++
// a las funciones exportadas de Rust en lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Genera el código C++ al que llama Rust.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

Building in Android

Crea un rust_binary que dependa de libcxx y de tu cc_library_static.

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

Interoperabilidad con Java

Java puede cargar objetos compartidos a través de la interfaz nativa de Java (JNI). El crate jni permite crear una biblioteca compatible.

En primer lugar, creamos una función de Rust para exportar a Java:

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Demo de FFI de Java.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// Implementación del método HelloWorld::hello.
#[no_mangle]
pub extern "system" fn Java_HelloWorld_hello(
    env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(name).unwrap().into();
    let greeting = format!("¡Hola, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_inner()
}
}

interoperability/java/Android.bp:

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

We then call this function from Java:

interoperability/java/HelloWorld.java:

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("Alice");
        System.out.println(output);
    }
}

interoperability/java/Android.bp:

java_binary {
    name: "helloworld_jni",
    srcs: ["HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

Ahora puedes compilar, sincronizar y ejecutar el binario:

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

Ejercicios

Este es un ejercicio de grupo: escogeremos uno de los proyectos con los que se esté trabajando e intentaremos integrar Rust en él. Algunas sugerencias:

• Llama a tu servicio de AIDL con un cliente escrito en Rust.

• Mueve una función desde tu proyecto a Rust y llámala.

Te Damos la Bienvenida a Rust en Chromium

Rust es compatible con bibliotecas de terceros en Chromium, con código pegamento propio para conectar Rust y el código de C++ de Chromium ya existente.

Hoy vamos a llamar a Rust para que haga algo divertido con las cadenas. Si tienes una esquina del código donde se muestra una cadena UTF8 al usuario, no dudes en seguir estas instrucciones en tu parte del código base en lugar de la parte exacta de la que hablamos.

Configurar

Asegúrate de que puedes compilar y ejecutar Chromium. Cualquier plataforma y conjunto de marcas de compilación es apto, siempre que tu código sea relativamente reciente (posición de commit 1223636 en adelante, correspondiente a noviembre del 2023):

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(Se recomienda una versión de depuración de componentes para que el tiempo de iteración sea más rápido. Esta es la opción predeterminada).

Consulta cómo compilar Chromium si aún no lo has hecho. Advertencia: el proceso de configuración para compilar Chromium puede tardar.

Se recomienda que tengas instalado Visual Studio Code.

Información sobre los ejercicios

Esta parte del curso consta de una serie de ejercicios que se complementan entre sí. Las iremos repartiendo a lo largo del curso en lugar de hacerlos todo al final. Si no tienes tiempo para completar una parte concreta, no te preocupes, podrás ponerte al día en la siguiente clase.

Comparación de los ecosistemas de Chromium y Cargo

The Rust community typically uses cargo and libraries from crates.io. Chromium is built using gn and ninja and a curated set of dependencies.

A la hora de escribir código en Rust, hay disponibles varias opciones:

• Usar gn y ninja con la ayuda de las plantillas de //build/rust/*.gni (por ejemplo, rust_static_library, que veremos más adelante). Se usan la cadena de herramientas y los crates auditados de Chromium.
• Usar cargo, pero restringiendo el uso de la cadena de herramientas y los crates auditados de Chromium.
• Usa cargo con una cadena de herramientas o crates descargados de Internet.

A partir de ahora, nos centraremos en gn y ninja, ya que así es como se puede compilar el código de Rust en el navegador Chromium. De igual forma, Cargo es una parte importante del ecosistema de Rust y deberías conservarlo en tu caja de herramientas.

Ejercicio rápido

Formad grupos pequeños para:

• Hacer una lluvia de ideas sobre situaciones en las que cargo pueda ofrecer ventajas y evaluar el perfil de riesgo.
• Debatir en qué herramientas, bibliotecas y grupos de personas hay que confiar al usar gn y ninja, cargo offline, etc.

Política de Chromium Rust

Chromium aún no permite usar Rust propio, excepto en casos excepcionales, según lo aprobado por Area Tech Leads.

La política de Chromium sobre bibliotecas de terceros se describe aquí. Se permite el uso de Rust para bibliotecas de terceros en algunos casos, incluido si son la mejor opción en cuanto al rendimiento o seguridad.

Muy pocas bibliotecas de Rust exponen directamente una API de C o C++, por lo que casi todas estas bibliotecas necesitarán una pequeña parte de código pegamento propio.

El código pegamento propio de Rust para un crate de terceros concreto normalmente debe guardarse en third_party/rust/<crate>/<version>/wrapper.

Por este motivo, el curso de hoy se centrará en los siguientes temas:

• Incorporación de bibliotecas Rust de terceros ("crates").
• Escribir código pegamento para poder usar esos crates desde Chromium C++.

Si esta política cambia con el tiempo, el curso irá evolucionando para adaptarse al cambio.

Reglas de Compilación (Build)

El código de Rust se suele compilar con cargo. Chromium se compila con gn y ninja para aumentar la eficiencia. Sus reglas estáticas permiten el máximo paralelismo. Rust no es una excepción.

Añadir código de Rust a Chromium

En algunos archivos BUILD.gn de Chromium, declara una rust_static_library:

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

También puedes añadir deps en otros segmentos de Rust. Más adelante, lo usaremos en función del código de terceros.

Incluir código de Rust unsafe

El código de Rust inseguro está prohibido en rust_static_library de forma predeterminada, por lo que no se podrá compilar. Si necesitas código de Rust inseguro, añade allow_unsafe = true al elemento de destino de gn. (Más adelante en el curso veremos circunstancias en las que es necesario hacerlo).

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

Depender de código de Rust desde Chromium C++

Solo tienes que añadir el elemento de destino que aparece arriba a los deps de algún elemento de destino de Chromium C++.

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# or source_set, static_library etc.
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

Los tipos se omiten en el código de Rust, lo que hace que un buen IDE sea aún más útil para C++. El código de Visual Studio funciona bien con Rust en Chromium. Para utilizarlo, haz lo siguiente:

• Asegúrate de que VSCode tenga la extensión rust-analyzer, no versiones anteriores de compatibilidad con Rust.
• gn gen out/Debug --export-rust-project (o el equivalente en tu directorio de salida).
• ln -s out/Debug/rust-project.json rust-project.json.

Ejercicio de reglas de compilación

En tu compilación de Chromium, añade un nuevo elemento de destino de Rust a //ui/base/build.gn que contenga lo siguiente:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("¡Saludos de parte Rust!")
}
}

Important: note that no_mangle here is considered a type of unsafety by the Rust compiler, so you'll need to allow unsafe code in your gn target.

Añade este nuevo elemento de destino de Rust como una dependencia de //ui/base:base. Declara esta función en la parte superior de ui/base/resource/resource_bundle.cc (más adelante veremos cómo se puede automatizar mediante herramientas de generación de enlaces):

extern "C" void hello_from_rust();

Llama a esta función desde algún lugar de ui/base/resource/resource_bundle.cc. Recomendamos hacerlo en la parte superior de ResourceBundle::RSMangleLocalizedString. Compila y ejecuta Chromium y asegúrate de que se imprima "¡Rust te manda un saludo!" muchas veces.

Si usas VSCode, ahora debes configurar Rust para que funcione correctamente en VSCode. Nos será útil en ejercicios posteriores. Si lo has completado correctamente, podrás hacer clic con el botón derecho y pulsar "Ir a la definición" en println!.

Dónde obtener ayuda

• Opciones disponibles de la plantilla gn rust_static_library
• Información sobre #[no_mangle]
• Información sobre extern "C"
• Información sobre el interruptor --export-rust-project de gn
• Cómo instalar rust-analyzer en VSCode

Probando

La comunidad de Rust suele crear las pruebas unitarias en un módulo situado en el mismo archivo fuente que el código que se está probando. Este tema ya se ha tratado antes en el curso y tiene este aspecto:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

En Chromium colocamos las pruebas unitarias en un archivo fuente independiente y continuamos con esta práctica con Rust. De esta forma, las pruebas se pueden encontrar de forma coherente y se evita volver a crear archivos .rs (en la configuración test).

Esta acción genera las siguientes opciones para probar el código de Rust en Chromium:

• Pruebas nativas de Rust (es decir, #[test]). No se recomienda hacerlas fuera de //third_party/rust.
• Pruebas gtest escritas en C++ y ejercicios con Rust mediante llamadas de FFI. Suficiente cuando el código de Rust es solo una capa fina de FFI y las pruebas unitarias existentes proporcionan suficiente cobertura para la función.
• Pruebas gtest creadas en Rust y usando el crate en prueba a través de su API pública (mediante pub mod for_testing { ... } si es necesario). Este es el tema de las siguientes diapositivas.

Biblioteca rust_gtest_interop

La biblioteca rust_gtest_interop permite hacer lo siguiente:

• Usar una función de Rust como caso de prueba gtest (con el atributo #[gtest(...)]).
• Usar expect_eq! y macros similares (similares a assert_eq!, pero sin que se produzcan pánicos o sin finalizar la prueba cuando la aserción falle).

Ejemplo:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Reglas GN para pruebas de Rust

La forma más sencilla de compilar pruebas gtest de Rust es añadirlas a un binario de prueba que ya contenga pruebas creadas en C++. Por ejemplo:

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

La creación de pruebas de Rust en una static_library independiente también funciona, pero es necesario declarar manualmente la dependencia en las bibliotecas de compatibilidad:

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

Macro chromium::import!

Después de añadir :my_rust_lib a GN deps, tenemos que aprender a importar y usar my_rust_lib desde my_rust_lib_unittest.rs. No hemos proporcionado un crate_name explícito para my_rust_lib, por lo que el nombre del crate se calcula en función de la ruta y el nombre de destino completos. Por suerte, podemos evitar trabajar con un nombre tan poco práctico usando la macro chromium::import! del crate chromium importado automáticamente:

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

En un segundo plano, la macro se expande a algo parecido a lo siguiente:

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

Puedes obtener más información en el comentario del documento de la macro chromium::import.

Ejercicio de pruebas

¡Vamos a hacer otro ejercicio!

En tu compilación de Chromium:

• Añade una función que se pueda probar junto a hello_from_rust. Aquí tienes algunas sugerencias: añadir dos números enteros recibidos como argumentos, calcular el enésimo número de la serie Fibonacci, sumar los enteros en un slice, etc.
• Añade un archivo ..._unittest.rs independiente con una prueba de la nueva función.
• Añade las nuevas pruebas a BUILD.gn.
• Compila las pruebas, ejecútalas y comprueba que la nueva prueba funciona.

Interoperabilidad con C++

La comunidad de Rust ofrece muchas opciones para la interoperabilidad de C++ y Rust, y continuamente se están desarrollando nuevas herramientas. Actualmente, Chromium usa la herramienta CXX.

Describe todos los límites de tu lenguaje en un lenguaje de definición de interfaz (que se parece mucho a Rust) y, a continuación, las herramientas CXX generarán declaraciones de funciones y tipos tanto en Rust como en C++.

Consulta el tutorial de CXX para ver un ejemplo completo de su uso.

Ejemplos

CXX necesita que se declare todo el límite de C++ o Rust en los módulos cxx::bridge del código fuente .rs.

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// Las definiciones de los tipos y las funciones de Rust se colocan aquí

Limitaciones de CXX

By far the most useful page when using CXX is the type reference.

CXX se adapta básicamente a los casos en los que:

• La interfaz de Rust-C++ es lo suficientemente sencilla como para se pueda declarar por completo.
• Solo estás usando los tipos compatibles de forma nativa con CXX, como std::unique_ptr, std::string o &[u8], entre otros.

Tiene muchas limitaciones, por ejemplo, la falta de compatibilidad con el tipo Option de Rust.

Estas restricciones nos limitan a usar Rust en Chromium solo para "nodos hoja" muy aislados, en lugar de para la interoperabilidad arbitraria de Rust-C++. Si te planteas un caso práctico de Rust en Chromium, un buen punto de partida es hacer un borrador de los enlaces de CXX para el límite del lenguaje para ver si te parece lo suficientemente sencillo.

Manejo de Errores en CXX

La compatibilidad con Result<T,E> de CXX se basa en excepciones de C++, por lo que no podemos usarlo en Chromium. Alternativas:

• La parte T de Result<T, E> puede:

  • Devolverse a través de parámetros externos (por ejemplo, mediante &mut T). Esto requiere que T se pueda transferir a través del límite de FFI. Por ejemplo, T tiene que ser:
    • Un tipo primitivo (como u32 o usize).
    • Un tipo compatible de forma nativa con cxx (como UniquePtr<T>) que tiene un valor predeterminado adecuado para usarlo en caso de fallo (a diferencia de Box<T>).
  • Mantenerse en el lado de Rust y mostrarse mediante referencia. Esto puede ser necesario cuando T es un tipo de Rust, que no se puede transmitir mediante el límite de FFI ni se puede almacenar en UniquePtr<T>.

• La parte E de Result<T, E> puede:

  • Devolverse como un valor booleano (por ejemplo, true representa el éxito y false representa el error).
  • En teoría, es posible conservar los detalles de los errores, pero hasta ahora no se ha necesitado en la práctica.

Manejo de Errores en CXX: Ejemplo de QR

El generador de código QR es un ejemplo en el que el valor booleano se utiliza para comunicar que el resultado es correcto o no, y dónde se puede transmitir el resultado correcto a través del límite de FFI:

#[cxx::bridge(namespace = "qr_code_generator")]
mod ffi {
    extern "Rust" {
        fn generate_qr_code_using_rust(
            data: &[u8],
            min_version: i16,
            out_pixels: Pin<&mut CxxVector<u8>>,
            out_qr_size: &mut usize,
        ) -> bool;
    }
}

CXX Error Handling: PNG Example

Un prototipo de un decodificador PNG ilustra lo que se puede hacer cuando el resultado correcto no se puede transmitir a través del límite de FFI:

#[cxx::bridge(namespace = "gfx::rust_bindings")]
mod ffi {
    extern "Rust" {
        /// Esto devuelve un equivalente de `Result<PngReader<'a>,
        /// ()>`, compatible con FFI.
        fn new_png_reader<'a>(input: &'a [u8]) -> Box<ResultOfPngReader<'a>>;

        /// Enlaces de C++ para el tipo `crate::png::ResultOfPngReader`.
        type ResultOfPngReader<'a>;
        fn is_err(self: &ResultOfPngReader) -> bool;
        fn unwrap_as_mut<'a, 'b>(
            self: &'b mut ResultOfPngReader<'a>,
        ) -> &'b mut PngReader<'a>;

        /// Enlaces de C++ para el tipo `crate::png::PngReader`.
        type PngReader<'a>;
        fn height(self: &PngReader) -> u32;
        fn width(self: &PngReader) -> u32;
        fn read_rgba8(self: &mut PngReader, output: &mut [u8]) -> bool;
    }
}

Usar cxx en Chromium

En Chromium, definimos un #[cxx::bridge] mod independiente para cada nodo hoja en el que queremos usar Rust. Normalmente hay uno por cada rust_static_library. Solo tienes que añadir

cxx_bindings = [ "my_rust_file.rs" ]
   # list of files containing #[cxx::bridge], not all source files
allow_unsafe = true

al elemento rust_static_library que ya tengas junto con crate_root y sources.

Los encabezados de C++ se generarán en una ubicación razonable, por lo que puedes simplemente incluir

#include "ui/base/my_rust_file.rs.h"

Encontrarás algunas funciones de utilidad en //base para convertir a y desde los tipos de Chromium C++ en tipos CXX de Rust y viceversa. Por ejemplo, SpanToRustSlice.

Ejercicio: Interoperabilidad con C++

Primera parte

• En el archivo de Rust que has creado anteriormente, añade un #[cxx::bridge], que especifica una sola función, denominada hello_from_rust, a la que se llamará desde C++, sin parámetros y sin devolver ningún valor.
• Modifica la función hello_from_rust anterior para eliminar extern "C" y #[no_mangle]. Ahora es solo una función estándar de Rust.
• Modifica el elemento de destino de gn para compilar estos enlaces.
• En el código C++, elimina la declaración de hello_from_rust. En su lugar, incluye el archivo de encabezado que se ha generado.
• Compila y ejecuta.

Segunda parte

Se recomienda jugar un poco con CXX, ya que nos ayuda a pensar en la flexibilidad que tiene Rust en Chromium.

Algunas cosas que probar:

• Vuelve a llamar a C++ desde Rust. Necesitarás lo siguiente:
  • Un archivo de encabezado adicional que puedes include! desde tu cxx::bridge. Deberás declarar la función de C++ en el nuevo archivo de encabezado.
  • Un bloque unsafe para llamar a una función de este tipo, o bien especificar la palabra clave unsafe en el #[cxx::bridge], como se describe aquí.
  • Es posible que también tengas que incluir #include "third_party/rust/cxx/v1/crate/include/cxx.h"
• Transfiere una cadena de C++ desde C++ a Rust.
• Pasa una referencia a un objeto de C++ en Rust.
• Obtén de forma intencional las firmas de la función de Rust que no coincidan con el #[cxx::bridge] y familiarízate con los errores que veas.
• Obtén de forma intencional las firmas de la función de C++ que no coincidan con el #[cxx::bridge] y familiarízate con los errores que veas.
• Transfiere un std::unique_ptr de algún tipo de C++ a Rust, para que a Rust le pertenezca algún objeto de C++.
• Crea un objeto de Rust y transmítelo a C++ para que sea su propietario. (Nota: necesitas utilizar un Box).
• Declara algunos métodos en un tipo de C++. Llámalos desde Rust.
• Declara algunos métodos en un tipo de Rust. Llámalos desde C++.

Tercera parte

Ahora que conoces los puntos fuertes y las limitaciones de la interoperabilidad de CXX, piensa en un par de casos prácticos de Rust en Chromium en los que la interfaz sea bastante sencilla. Haz un boceto sobre cómo definirías esa interfaz.

Dónde obtener ayuda

• The cxx binding reference
• La plantilla gn rust_static_library

Añadir crates de terceros

Las bibliotecas de Rust se llaman "crates" y se encuentran en crates.io. Es habitual que los crates de Rust dependen los unos de otros.