Bem-vindos ao Comprehensive Rust 🦀

Este é um curso gratuito de Rust desenvolvido pela equipe do Android no Google. O curso abrange o espectro completo da linguagem, desde sintaxe básica até tópicos avançados como 'generics' e tratamento de erros.

A versão mais recente do curso pode ser encontrada em https://google.github.io/comprehensive-rust/. Se você estiver lendo em outro lugar, por favor verifique lá por atualizações.

O curso está disponível em outros idiomas. Selecione seu idioma preferido no canto superior direito da página ou verifique a página de Traduções para uma lista de todas as traduções disponíveis.

O curso também está disponível como PDF.

O objetivo do curso é ensinar Rust a você. Nós assumimos que você não saiba nada sobre Rust e esperamos:

• Dar a você uma compreensão abrangente da linguagem e da sintaxe de Rust.
• Permitir que você modifique programas existentes e escreva novos programas em Rust.
• Demonstrar expressões idiomáticas comuns de Rust.

Nós chamamos os quatro primeiros dias do curso de Fundamentos do Rust.

Em seguida, você está convidado(a) a mergulhar a fundo em um ou mais tópicos especializados:

• Android: um curso de meio dia sobre a utilização de Rust no desenvolvimento para a plataforma Android (AOSP). Isto inclui interoperabilidade com C, C++ e Java.
• Chromium: um curso de meio dia sobre a utilização de Rust em navegadores baseados em Chromium. Isto inclui interoperabilidade com C++ e como incluir crates de terceiros no Chromium.
• Bare-metal: uma aula de um dia sobre a utilização de Rust para o desenvolvimento "bare metal" (sistema embarcado). Tanto micro-controladores quanto processadores de aplicação são cobertos.
• Concorrência: uma aula de um dia inteiro sobre concorrência em Rust. Nós cobrimos tanto concorrência clássica (escalonamento preemptivo utilizando threads e mutexes) quanto concorrência async/await (multitarefa cooperativa utilizando futures).

Fora do escopo

Rust é uma linguagem extensa e não conseguiremos cobrir tudo em poucos dias. Alguns assuntos que não são objetivos deste curso são:

• Aprender a criar macros: por favor confira Capítulo 19.5 em Rust Book e Rust by Example para esse fim.

Premissas

O curso pressupõe que você já saiba programar. Rust é uma linguagem de tipagem estática e ocasionalmente faremos comparações com C e C++ para melhor explicar ou contrastar a abordagem do Rust.

Se você sabe programar em uma linguagem de tipagem dinâmica, como Python ou JavaScript, então você também será capaz de acompanhar.

Conduzindo o Curso

Esta página é para o instrutor do curso.

Aqui estão algumas informações básicas sobre como estamos conduzindo o curso internamente no Google.

Normalmente realizamos as aulas das 9h às 16h, com uma pausa de 1 hora para o almoço no meio. Isso deixa 3 horas para a aula da manhã e 3 horas para a aula da tarde. Ambas as sessões contêm várias pausas e tempo para os alunos trabalharem nos exercícios.

Antes de oferecer o curso, você precisa:

1. Familiarize-se com o material do curso. Incluímos notas do instrutor para ajudar a destacar os pontos principais (ajude-nos contribuindo com mais notas!). Ao apresentar, certifique-se de abrir as notas do instrutor em um pop-up (clique no link com uma pequena seta ao lado de "Speaker Notes" ou "Notas do Instrutor"). Desta forma você tem uma tela limpa para apresentar à turma.

2. Decida as datas. Como o curso leva pelo menos quatro dias completos, recomendamos que você agende os dias ao longo de duas semanas. Os participantes do curso disseram que eles acham útil ter um espaço no curso, pois os ajuda a processar todas as informações que lhes damos.

3. Encontre uma sala grande o suficiente para seus participantes presenciais. Recomendamos turmas de 15 a 25 pessoas. Isso é pequeno o suficiente para que as pessoas se sintam confortáveis fazendo perguntas --- também é pequeno o suficiente para que um instrutor tenha tempo para responder às perguntas. Certifique-se de que a sala tenha mesas para você e para os alunos: todos vocês precisam ser capazes de sentar e trabalhar com seus laptops. Em particular, você fará muita codificação ao vivo como instrutor, portanto, um pódio não será muito útil para você.

4. No dia do seu curso, chegue um pouco mais cedo na sala para acertar as coisas. Recomendamos apresentar diretamente usando mdbook serve rodando em seu laptop (consulte as instruções de instalação). Isso garante um desempenho ideal sem atrasos conforme você muda de página. Usar seu laptop também permitirá que você corrija erros de digitação enquanto você ou os participantes do curso os identificam.

5. Deixe as pessoas resolverem os exercícios sozinhas ou em pequenos grupos. Normalmente gastamos de 30 a 45 minutos em exercícios pela manhã e à tarde (incluindo o tempo para revisar as soluções). Tenha certeza de perguntar às pessoas se elas estão em dificuldades ou se há algo em que você possa ajudar. Quando você vir que várias pessoas têm o mesmo problema, chame a turma e ofereça uma solução, por exemplo, mostrando às pessoas onde encontrar as informações relevantes na biblioteca padrão ("standard library").

Isso é tudo, boa sorte no curso! Esperamos que seja tão divertido para você como tem sido para nós!

Por favor, dê seu feedback depois para que possamos continuar melhorando o curso. Adoraríamos saber o que funcionou bem para você e o que pode ser melhorado. Seus alunos também são muito bem-vindos para nos enviar feedback!

Estrutura do Curso

Esta página é para o instrutor do curso.

Fundamentos do Rust

Os primeiros quatro dias compõem os Fundamentos do Rust. Os dias são rápidos e cobrimos bastante counteúdo!

Agenda do curso:

• Dia 1 Manhã (2 horas e 5 minutos, incluindo intervalos)

• Dia 1 Tarde (2 horas e 35 minutos, incluindo intervalos)

• Dia 2 Manhã (2 horas and 10 minutos, incluindo intervalos)

• Dia 2 Tarde (3 horas e 15 minutos, incluindo intervalos)

• Dia 3 Manhã (2 horas and 20 minutos, incluindo intervalos)

• Dia 3 Tarde (1 hora and 55 minutos, incluindo intervalos)

• Dia 4 Manhã (2 horas and 40 minutos, incluindo intervalos)

• Dia 4 Tarde (2 horas and 15 minutos, incluindo intervalos)

Análises Detalhadas

Além do curso de 4 dias sobre Fundamentos de Rust, nós abordamos alguns tópicos mais especializados:

Rust para Android

O Rust para Android é um curso de meio dia sobre o uso de Rust para o desenvolvimento na plataforma Android. Isso inclui interoperabilidade com C, C++ e Java.

Você precisará de um checkout do AOSP. Faça um checkout do repositório do curso no mesmo computador e mova o diretório src/android/ para a raiz do seu checkout do AOSP. Isso garantirá que o sistema de compilação do Android veja os arquivos Android.bp em src/android/.

Certifique-se de que adb sync funcione com seu emulador ou dispositivo físico e pré-compile todos os exemplos do Android usando src/android/build_all.sh. Leia o roteiro para ver os comandos executados e verifique se eles funcionam quando você os executa manualmente.

Rust para Chromium

O Rust para Chromium é um curso de meio dia sobre o uso de Rust como parte do navegador Chromium. Ele inclui o uso de Rust no sistema de compilação gn do Chromium, a inclusão de bibliotecas de terceiros ("crates") e interoperabilidade com C++.

Você precisará ser capaz de compilar o Chromium --- uma compilação de componentes de depuração é recomendada para velocidade, mas qualquer compilação funcionará. Certifique-se de que você possa executar o navegador Chromium que você compilou.

Rust Bare-Metal

O Rust Bare-Metal é uma aula de um dia inteiro sobre o uso de Rust para o desenvolvimento bare-metal (sistema embarcado). Tanto micro-controladores quanto processadores de aplicação são cobertos.

Para a parte do micro-controlador, você precisará comprar a placa de desenvolvimento BBC micro:bit v2 com antecedência. Todos precisarão instalar vários pacotes, conforme descrito na página inicial.

Concorrência em Rust

Concorrência em Rust é uma aula de um dia sobre concorrência clássica e concorrência async/await.

Você precisará de um novo crate configurado e as dependências baixadas e prontas para uso. Você pode então copiar/colar os exemplos para src/main.rs para experimentá-los:

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

Agenda do curso:

• Morning (3 hours and 20 minutes, including breaks)

• Afternoon (3 hours and 20 minutes, including breaks)

Formato

O curso foi projetado para ser bastante interativo e recomendamos deixar as perguntas conduzirem a exploração do Rust!

Atalhos de Teclado

Existem vários atalhos de teclado úteis no mdBook:

• Arrow-Left: Navigate to the previous page.
• Arrow-Right: Navigate to the next page.
• Ctrl + Enter: Execute the code sample that has focus.
• s: Activate the search bar.

Traduções

O curso foi traduzido para outros idiomas por um grupo de voluntários maravilhosos:

• Português do Brasil por @rastringer, @hugojacob, @joaovicmendes e @henrif75.
• Chinês (Simplificado) por @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK e @nodmp.
• Chinês (Tradicional) por @hueich, @victorhsieh, @mingyc, @kuanhungchen e @johnathan79717.
• Japonês por @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi e @kantasv.
• Coreano por @keispace, @jiyongp, @jooyunghan, e @namhyung.
• Espanhol por @deavid.
• Ucraniano por @git-user-cpp, @yaremam e @reta.

Use o seletor de idioma no canto superior direito para alternar entre os idiomas.

Traduções Incompletas

Há um grande número de traduções em andamento. Nós referenciamos as traduções mais recentemente atualizadas:

• Árabe por @younies
• Bengali por @raselmandol.
• Francês por @KookaS, @vcaen e @AdrienBaudemont.
• Alemão por @Throvn e @ronaldfw.
• Italiano por @henrythebuilder e @detro.

Se você quiser ajudar com essa iniciativa, consulte nossas instruções sobre como proceder. As traduções são coordenadas no issue tracker.

Usando o Cargo

Quando você começar a ler sobre Rust, logo conhecerá o Cargo, a ferramenta padrão usada no ecossistema Rust para criar e executar aplicativos Rust. Aqui nós queremos dar uma breve visão geral do que é o Cargo e como ele se encaixa no ecossistema mais amplo e como ele se encaixa neste treinamento.

Instalação

Por favor, siga as instruções em https://rustup.rs/.

Isso fornecerá a ferramenta de compilação Cargo (cargo) e o compilador Rust (rustc). Você também obterá o rustup, um utilitário de linha de comando que você pode usar para instalar diferentes versões do compilador.

Depois de instalar o Rust, você deve configurar seu editor ou IDE para trabalhar com o Rust. A maioria dos editores faz isso conversando com o rust-analyzer, que fornece auto-completar e funcionalidade de salto para definição para VS Code, Emacs, Vim/Neovim e muitos outros. Também há um IDE diferente disponível chamado RustRover.

O Ecossistema Rust

O ecossistema Rust consiste em várias ferramentas, das quais as principais são:

• rustc: o compilador Rust que converte arquivos .rs em binários e outros formatos intermediários.

• cargo: o gerenciador de dependências e ferramenta de compilação do Rust. O Cargo sabe como baixar dependências, normalmente hospedadas em https://crates.io, e as passará para o rustc quando compilar o seu projeto. O Cargo também vem com um gerenciador de testes embutido que é utilizado para a execução de testes unitários.

• rustup: o instalador e atualizador do conjunto de ferramentas do Rust. Esta ferramenta é utilizada para instalar e atualizar o rustc e o cargo quando novas versões do Rust forem lançadas. Além disso, rustup também pode baixar a documentação da biblioteca padrão. Você pode ter múltiplas versões do Rust instaladas ao mesmo tempo e rustup permitirá que você alterne entre elas conforme necessário.

Exemplos de Código neste Treinamento

Para este treinamento, exploraremos principalmente a linguagem Rust por meio de exemplos que podem ser executados através do seu navegador. Isso torna a instalação muito mais fácil e garante uma experiência consistente para todos.

A instalação do Cargo ainda assim é incentivada: será mais fácil para você fazer os exercícios. No último dia, faremos um exercício maior que mostra como trabalhar com dependências e para isso você precisará do Cargo.

Os blocos de código neste curso são totalmente interativos:

fn main() {
    println!("Edite-me!");
}

You can use Ctrl + Enter to execute the code when focus is in the text box.

Executando Código Localmente com o Cargo

Se você quiser experimentar o código em seu próprio sistema, precisará primeiro instalar o Rust. Faça isso seguindo as instruções no Livro do Rust. Isso deve fornecer o rustc e o cargo funcionando. Quando este curso foi escrito, as últimas versões estáveis do Rust são:

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

Você também pode usar qualquer versão posterior, pois o Rust mantém compatibilidade com versões anteriores.

Com isso finalizado, siga estas etapas para criar um binário Rust a partir de um dos exemplos deste treinamento:

1. Clique no botão "Copy to clipboard" ("Copiar para a área de transferência") no exemplo que deseja copiar.

2. Use cargo new exercise para criar um novo diretório exercise/ para o seu código:

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

3. Navegue até exercise/ e use cargo run para compilar e executar seu binário:

   $ 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. Substitua o código gerado em src/main.rs pelo seu próprio código. Por exemplo, usando o exemplo da página anterior, faça src/main.rs parecer como

   fn main() {
       println!("Edite-me!");
   }

5. Use cargo run para compilar e executar seu binário atualizado:

   $ 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. Use cargo check para verificar rapidamente se há erros em seu projeto, use cargo build para compilá-lo sem executá-lo. Você encontrará a saída em target/debug/ para uma compilação de depuração normal. Use cargo build --release para produzir um binário otimizado em target/release/.

7. Você pode adicionar dependências para seu projeto editando Cargo.toml. Quando você execute os comandos cargo, ele irá baixar e compilar automaticamente dependências para você.

Bem-vindos ao Dia 1

Este é o primeiro dia de Fundamentos do Rust. Nós iremos cobrir muitos pontos hoje:

• Sintaxe Rust básica: variáveis, tipos escalares e compostos, enums, structs, referências, funções e métodos.
• Tipos e Inferência de Tipo
• Construções de fluxo de controle: loops, condicionais, e assim por diante.
• Tipos definidos pelo usuário: structs e enums.
• Correspondência de padrões: desestruturando enums, structs, e matrizes.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 5 minutes. It contains:

Olá, Mundo

This segment should take about 15 minutes. It contains:

O que é Rust?

Rust é uma nova linguagem de programação que teve sua versão 1.0 lançada em 2015:

• Rust é uma linguagem compilada estaticamente e tem um papel semelhante ao C++
  • rustc usa o LLVM como seu backend.
• Rust suporta muitas plataformas e arquiteturas:
  • x86, ARM, WebAssembly, ...
  • Linux, Mac, Windows, ...
• Rust é usado em uma ampla gama de dispositivos:
  • firmware e carregadores de boot,
  • smart displays,
  • celulares,
  • desktops,
  • servidores.

Benefícios do Rust

Alguns pontos exclusivos do Rust:

• Segurança de memória em tempo de compilação - classes inteiras de bugs de memória são prevenidas em tempo de compilação

  • Sem variáveis não inicializadas.
  • Sem double-frees.
  • Sem use-after-free.
  • Sem ponteiros NULL.
  • Sem mutexes bloqueados esquecidos.
  • Sem concorrência de dados entre threads.
  • Sem invalidação de iteradores.

• Sem comportamento indefinido em tempo de execução - o que uma instrução Rust executa nunca é deixado indefinido

  • O acesso a matrizes tem limites verificados.
  • Estouro de números inteiros é definido ("pânico" ou wrap-around).

• Recursos de linguagem modernos - tão expressivos e ergonômicos quanto linguagens de alto nível

  • Enums e correspondência de padrões.
  • Genéricos (Generics).
  • FFI sem overhead.
  • Abstrações de custo zero.
  • Excelentes mensagens de erro do compilador.
  • Gerenciador de dependências integrado.
  • Suporte integrado para testes.
  • Excelente suporte ao protocolo de servidor de linguagem (LSP).

Playground

O Rust Playground fornece uma maneira fácil de executar pequenos programas em Rust, e é a base para os exemplos e exercícios neste curso. Tente executar o programa "hello-world" com o qual ele começa. Ele vem com algumas funcionalidades úteis:

• Em "Tools", use a opção rustfmt para formatar seu código da maneira "padrão".

• Rust tem dois principais "perfis" (profiles) para gerar código: Debug (verificações de tempo de execução extras, menos otimização) e Release (menos verificações de tempo de execução, muita otimização). Estes são acessíveis em "Debug" no topo.

• Se você estiver interessado, use "ASM" em "..." para ver o código assembly gerado.

Tipos e Valores

This segment should take about 40 minutes. It contains:

Olá, Mundo

Vamos pular para o programa em Rust mais simples possível, o clássico "Olá Mundo":

fn main() {
    println!("Hello 🌍!");
}

O que você vê:

• Funções são introduzidas com fn.
• Os blocos são delimitados por chaves como em C e C++.
• A função main é o ponto de entrada do programa.
• Rust tem macros "higiênicas", println! é um exemplo disso.
• As strings Rust são codificadas em UTF-8 e podem conter qualquer caractere Unicode.

Variáveis

Rust fornece segurança de tipo por meio de tipagem estática. Variáveis são vinculadas com let (let bindings):

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

Valores

Aqui estão alguns tipos básicos integrados, e a sintaxe para valores literais de cada tipo.

Os tipos têm os seguintes tamanhos:

• iN, uN e fN têm N bits,
• isize e usize são do tamanho de um ponteiro,
• char tem 32 bits,
• bool tem 8 bits.

Aritimética

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

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

Inferência de Tipo

Rust verá como a variável é usada para determinar o 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);
    // ERRO: nenhuma implementação para `{float} == {integer}`
}

Exercício: Fibonacci

A sequência de Fibonacci começa com [0,1]. Para n>1, o n-ésimo número de Fibonacci é calculado recursivamente como a soma dos n-1-ésimos e n-2-ésimos números de Fibonacci.

Escreva uma função fib(n) que calcula o n-ésimo número de Fibonacci. Quando esta função causará um pânico?

fn fib(n: u32) -> u32 {
    if n < 2 {
        // O caso base.
        todo!("Implemente isso")
    } else {
        // O caso recursivo.
        todo!("Implemente isso")
    }
}

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

Solução

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));
}

Fundamentos de Controle de Fluxo

This segment should take about 40 minutes. It contains:

Expressões if

Você usa expressões if exatamente como declarações if em outras linguagens:

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

Além disso, você pode usá-lo como uma expressão. A última expressão de cada bloco se torna o valor da expressão if

fn main() {
    let x = 10;
    let size = if x < 20 { "pequeno" } else { "grande" };
    println!("tamanho do número: {}", size);
}

Loops

Há três palavras-chave de loop em Rust: while, loop e for:

while

A palavra-chave while funciona de maneira muito similar a outras linguagens, executando o corpo do loop enquanto a condição for verdadeira.

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

for

O loop for itera sobre intervalos de valores ou os itens em uma coleção:

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

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

loop

O loop loop apenas executa um loop para sempre, até um break.

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

break e continue

Se você quiser iniciar imediatamente a próxima iteração use continue.

Se você quiser sair de qualquer loop cedo, use break. Para loop, isso pode receber uma expressão opcional que se torna o valor da expressão loop.

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

Rótulos (Labels)

Ambos continue e break podem opcionalmente receber um label (rótulo) como argumento que é usado para sair de loops aninhados:

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 pesquisados: {elements_searched}");
}

Blocos e Escopos

Blocos

Um bloco em Rust contêm uma sequência de expressões, delimitadas por chaves {}. Cada bloco tem um valor e um tipo, que são os da última expressão do bloco:

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

Se a última expressão terminar com ;, o valor resultante e o tipo será ().

Escopos e Shadowing (Sobreposição)

O escopo de uma variável é limitado ao bloco que a contém.

Você pode sobrepor (shadow) variáveis, tanto aquelas de escopos externos quanto variáveis do mesmo escopo:

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

        let a = true;
        println!("sobreposto no escopo interno: {a}");
    }

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

Funções

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

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

Macros

Macros são expandidas em código Rust durante a compilação e podem receber um número variável de argumentos. Elas são distinguidas por um ! no final. A biblioteca padrão do Rust inclui uma variedade de macros úteis.

• println!(format, ..) imprime uma linha na saída padrão, aplicando a formatação descrita em std::fmt.
• format!(format, ..) funciona exatamente como println!, mas retorna o resultado como uma string.
• dbg!(expressão) registra o valor da expressão e o retorna.
• todo!() marca um trecho de código como não implementado. Se executado, gerará um pânico.
• unreachable!() marca um trecho de código como inalcançável. Se executado, gerará um 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));
}

Exercício: Sequência de Collatz

The Collatz Sequence is defined as follows, for an arbitrary n₁ greater than zero:

• If n_i is 1, then the sequence terminates at n_i.
• If n_i is even, then n_i+1 = n_i / 2.
• If n_i is odd, then n_i+1 = 3 * n_i + 1.

For example, beginning with n₁ = 3:

• 3 is odd, so n₂ = 3 * 3 + 1 = 10;
• 10 is even, so n₃ = 10 / 2 = 5;
• 5 is odd, so n₄ = 3 * 5 + 1 = 16;
• 16 is even, so n₅ = 16 / 2 = 8;
• 8 is even, so n₆ = 8 / 2 = 4;
• 4 is even, so n₇ = 4 / 2 = 2;
• 2 is even, so n₈ = 1; and
• a sequência termina.

Escreva uma função para calcular o comprimento da sequência de Collatz para um dado n inicial.

/// Determine o comprimento da sequência de Collatz começando em `n`.
fn collatz_length(mut n: i32) -> u32 {
  todo!("Implemente isso")
}

fn main() {
  todo!("Implemente isso")
}

Solução

/// Determine o comprimento da sequência de Collatz começando em `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!("Comprimento: {}", collatz_length(11));
}

Bem-vindos de volta

Including 10 minute breaks, this session should take about 2 hours and 35 minutes. It contains:

Tuplas e Matrizes

This segment should take about 35 minutes. It contains:

Matrizes

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);
}

Iterator de Matrizes

O comando for suporta iteração sobre matrizes (mas não 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);
        }
    }
}

Padrões e Desestruturação

Quando se trabalha com tuplas e outros valores estruturados, é comum querer extrair os valores internos em variáveis locais. Isso pode ser feito manualmente acessando diretamente os valores internos:

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

No entanto, Rust também suporta o uso de correspondência de padrões (pattern matching) para desestruturar um valor maior em suas partes constituintes:

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

Exercício: Matrizes Aninhadas

Matrizes podem conter outras matrizes:

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

Qual é o tipo desta variável?

Use uma matriz como a acima para escrever uma função transpose que transporá uma matriz (transformar linhas em colunas):

Copie o código abaixo para https://play.rust-lang.org/ e implemente as funções: Esta função opera apenas em matrizes 3x3.

// TODO: remova isto quando você terminar sua implementação.
#![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], // <-- o comentário faz com que o rustfmt adicione uma nova linha
        [201, 202, 203],
        [301, 302, 303],
    ];

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

Solução

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], // <-- o comentário faz com que o rustfmt adicione uma nova linha
        [201, 202, 203],
        [301, 302, 303],
    ];

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

Referências

This segment should take about 55 minutes. It contains:

Referências Compartilhadas

Uma referência fornece uma maneira de acessar outro valor sem assumir a responsabilidade pelo valor, e também é chamada de "empréstimo". Referências compartilhadas são somente leitura e os dados referenciados não podem ser alterados.

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

Uma referência compartilhada a um tipo T tem tipo &T. Um valor de referência é feito com o operador &. O operador * "desreferencia" uma referência, produzindo seu valor.

Rust estaticamente proibirá referências pendentes:

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

Referências Exclusivas

Referências exclusivas, também conhecidas como referências mutáveis, permitem alterar o valor a que se referem. Eles têm tipo &mut T.

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

Slices (Fatias)

Uma slice (fatia) oferece uma visão de uma coleção maior:

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:?}");
}

• Slices pegam dados emprestados (_borrow) do tipo original.
• Pergunta: O que acontece se você modificar a[3] imediatamente antes de imprimir s?

Strings

Agora podemos entender os dois tipos de strings em Rust:

• &str é uma slice de bytes codificados em UTF-8, similar a &[u8].
• String é um buffer owned de bytes codificados em UTF-8, similar a Vec<T>.

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

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

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

Exercício: Geometria

Vamos criar algumas funções de utilidade para geometria tridimensional, representando um ponto como [f64;3]. Cabe a você determinar as assinaturas das funções.

// Calcule a magnitude de um vetor somando os quadrados de suas coordenadas
// e tirando a raiz quadrada. Use o método `sqrt()` para calcular a raiz quadrada,
// como `v.sqrt()`.


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

// Normalize um vetor calculando sua magnitude e dividindo todas as suas
// coordenadas por essa magnitude.


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

// Use o seguinte `main` para testar seu trabalho.

fn main() {
    println!("Magnitude de um vetor unitário: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude de {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude de {v:?} após normalização: {}", magnitude(&v));
}

Solução

/// Calcule a magnitude do vetor dado.
fn magnitude(vector: &[f64; 3]) -> f64 {
    let mut mag_squared = 0.0;
    for coord in vector {
        mag_squared += coord * coord;
    }
    mag_squared.sqrt()
}

/// Altere a magnitude do vetor para 1.0 sem alterar sua direção.
fn normalize(vector: &mut [f64; 3]) {
    let mag = magnitude(vector);
    for item in vector {
        *item /= mag;
    }
}

fn main() {
    println!("Magnitude de um vetor unitário: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude de {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude de {v:?} após normalização: {}", magnitude(&v));
}

Tipos Definidos pelo Usuário

This segment should take about 50 minutes. It contains:

Structs (Estruturas) Nomeadas

Como C e C++, Rust tem suporte para structs personalizadas:

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

fn describe(person: &Person) {
    println!("{} tem {} anos.", 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);
}

Structs de Tuplas

Se os nomes dos campos não forem importantes, você pode usar uma struct de tupla:

struct Point(i32, i32);

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

Isso é comumente utilizado para wrappers (invólucros) com campo único (chamados newtypes):

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

fn compute_thruster_force() -> PoundsOfForce {
    todo!("Pergunte para um cientista de foguetes da NASA")
}

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

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

Enums (Enumerações)

A palavra-chave enum permite a criação de um tipo que possui algumas variantes diferentes:

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

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

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

static

Variáveis estáticas permanecerão válidas durante toda a execução do programa e, portanto, não serão movidas:

static BANNER: &str = "Bem-vindos ao RustOS 3.14";

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

Conforme observado no Rust RFC Book, eles não são expandidos no local (inlined) quando utilizados e possuem um local de memória real associado. Isso é útil para código inseguro (unsafe) e embarcado, e a variável é válida durante toda a execução do programa. Quando um valor de escopo global não tem uma razão para precisar de identidade de objeto, geralmente const é preferido.

const

Constantes são avaliadas em tempo de compilação e seus valores são expandidos no próprio local (inlined) onde quer que sejam usados:

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:?}");
}

De acordo com o Rust RFC Book, eles são expandidos no próprio local (inline) quando utilizados.

Somente funções marcadas como const podem ser chamadas em tempo de compilação para gerar valores const. As funções const podem, entretanto, ser chamadas em tempo de execução.

Aliases (Apelidos) de Tipo

Um alias de tipo cria um nome para outro tipo. Os dois tipos podem ser usados ​​de forma intercambiável.

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// _Aliases_ são mais úteis com tipos longos e complexos:
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

Exercício: Eventos de Elevador

Vamos criar uma estrutura de dados para representar um evento em um sistema de controle de elevador. Cabe a você definir os tipos e funções para construir vários eventos. Use #[derive(Debug)] para permitir que os tipos sejam formatados com {:?}.

Este exercício requer apenas a criação e o preenchimento de estruturas de dados para que o main seja executado sem erros. A próxima parte do curso abordará a obtenção de dados dessas estruturas.

#[derive(Debug)]
/// Um evento no sistema de elevador ao qual o controlador deve reagir.
enum Event {
    // TODO: adicionar variantes necessárias
}

/// Uma direção da viagem.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// O elevador chegou no andar dado.
fn car_arrived(floor: i32) -> Event {
    todo!()
}

/// As portas do elevador se abriram.
fn car_door_opened() -> Event {
    todo!()
}

/// As portas do elevador se fecharam.
fn car_door_closed() -> Event {
    todo!()
}

/// Um botão direcional foi pressionado em um saguão de elevador no andar dado.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    todo!()
}

/// Um botão de andar foi pressionado no elevador.
fn car_floor_button_pressed(floor: i32) -> Event {
    todo!()
}

fn main() {
    println!(
        "Um passageiro do térreo pressionou o botão para subir: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("O elevador chegou no térreo: {:?}", car_arrived(0));
    println!("A porta do elevador se abriu: {:?}", car_door_opened());
    println!(
        "Um passageiro pressionou o botão do 3º andar: {:?}",
        car_floor_button_pressed(3)
    );
    println!("A porta do elevador se fechou: {:?}", car_door_closed());
    println!("O elevador chegou no 3º andar: {:?}", car_arrived(3));
}

Solução

#[derive(Debug)]
/// Um evento no sistema de elevador ao qual o controlador deve reagir.
enum Event {
    /// Um botão foi pressionado.
    ButtonPressed(Button),

    /// O elevador chegou no andar dado.
    CarArrived(Floor),

    /// As portas do elevador se abriram.
    CarDoorOpened,

    /// As portas do elevador se fecharam.
    CarDoorClosed,
}

/// Um andar é representado como um inteiro.
type Floor = i32;

/// Uma direção da viagem.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// Um botão acessível ao usuário.
#[derive(Debug)]
enum Button {
    /// Um botão no saguão do elevador no andar dado.
    LobbyCall(Direction, Floor),

    /// Um botão de andar dentro do elevador.
    CarFloor(Floor),
}

/// O elevador chegou no andar dado.
fn car_arrived(floor: i32) -> Event {
    Event::CarArrived(floor)
}

/// As portas do elevador se abriram.
fn car_door_opened() -> Event {
    Event::CarDoorOpened
}

/// As portas do elevador se fecharam.
fn car_door_closed() -> Event {
    Event::CarDoorClosed
}

/// Um botão direcional foi pressionado em um saguão de elevador no andar dado.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    Event::ButtonPressed(Button::LobbyCall(dir, floor))
}

/// Um botão de andar foi pressionado no elevador.
fn car_floor_button_pressed(floor: i32) -> Event {
    Event::ButtonPressed(Button::CarFloor(floor))
}

fn main() {
    println!(
        "Um passageiro do térreo pressionou o botão para subir: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("O elevador chegou no térreo: {:?}", car_arrived(0));
    println!("A porta do elevador se abriu: {:?}", car_door_opened());
    println!(
        "Um passageiro pressionou o botão do 3º andar: {:?}",
        car_floor_button_pressed(3)
    );
    println!("A porta do elevador se fechou: {:?}", car_door_closed());
    println!("O elevador chegou no 3º andar: {:?}", car_arrived(3));
}

Bem-vindos ao Dia 2

Agora que vimos uma boa quantidade de Rust, hoje focaremos no sistema de tipos do Rust:

• Correspondência de padrões: extraindo de dados de estruturas.
• Métodos: associando funções com tipos.
• Traits: comportamentos compartilhados por múltiplos tipos.
• Genéricos: parametrizando tipos em outros tipos.
• Tipos e traits da biblioteca padrão: um passeio pela rica biblioteca padrão do Rust.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

Correspondência de Padrões

This segment should take about 1 hour. It contains:

Correspondendo Valores

A palavra-chave match permite que você corresponda um valor a um ou mais padrões (patterns). As comparações são feitas de cima para baixo e a primeira correspondência encontrada é selecionada.

Os padrões podem ser valores simples, similarmente a switch em C e C++:

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("Encerrando"),
        'a' | 's' | 'w' | 'd'     => println!("Movendo por aí"),
        '0'..='9'                 => println!("Entrada de número"),
        key if key.is_lowercase() => println!("Minúsculas: {key}"),
        _                         => println!("Alguma outra coisa"),
    }
}

O padrão _ é um padrão curinga que corresponde a qualquer valor. As expressões devem ser irrefutáveis, o que significa que cobre todas as possibilidades, então _ é frequentemente usado como o último caso de captura.

Correspondência pode ser usada como uma expressão. Assim como if, cada braço de correspondência deve ter o mesmo tipo. O tipo é a última expressão do bloco, se houver. No exemplo acima, o tipo é ().

Uma variável no padrão (key neste exemplo) criará uma ligação que pode ser usada dentro do braço de correspondência.

Uma guarda de correspondência faz com que o braço corresponda somente se a condição for verdadeira.

Structs

Como tuplas, structs também podem ser desestruturados por meio de correspondência:

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}, outros campos foram ignorados"),
    }
}

Enums (Enumerações)

Como tuplas, enums também podem ser desestruturados por meio de correspondência:

Os padrões também podem ser usados para vincular variáveis a partes de seus valores. É assim que você inspeciona a estrutura de seus tipos. Vamos começar com um tipo enum simples:

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!("não é possível dividir {n} em duas partes iguais"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} divido em dois é {half}"),
        Result::Err(msg) => println!("desculpe, aconteceu um erro: {msg}"),
    }
}

Aqui usamos a verificação de correspondência para desestruturar o valor contido em Result. Na primeira verificação de correspondência, half está vinculado ao valor dentro da variante Ok. Na segunda, msg está vinculado à mensagem de erro.

Controle de Fluxo Let

Rust possui algumas construções de fluxo de controle que diferem de outras linguagens. Elas são usadas para correspondência de padrões:

• Expressões if let
• Expressões let else
• Expressões while let

Expressões if let

A expressão if let lhe permite executar um código diferente caso um valor corresponde a um padrão:

use std::time::Duration;

fn sleep_for(secs: f32) {
    if let Ok(dur) = Duration::try_from_secs_f32(secs) {
        std::thread::sleep(dur);
        println!("dormiu por {:?}", dur);
    }
}

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

Expressões let else

Para o caso comum de corresponder a um padrão e retornar da função, use let else. O caso "else" deve divergir (return, break ou pânico - qualquer coisa, exceto cair no final do bloco).

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("obteve None"));
    };

    let first_byte_char = if let Some(first_byte_char) = s.chars().next() {
        first_byte_char
    } else {
        return Err(String::from("obteve uma string vazia"));
    };

    if let Some(digit) = first_byte_char.to_digit(16) {
        Ok(digit)
    } else {
        Err(String::from("não é um dígito hexadecimal"))
    }
}

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

Similar a if let, há uma variante while let que testa repetidamente se um valor corresponde a um padrão:

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!)
}

Aqui String::pop retorna Some(c) até que a string esteja vazia e depois ela retornará None. O while let nos permite iterar por todos os itens.

#![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("obteve None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("obteve uma string vazia"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("não é um dígito hexadecimal"));
    };

    return Ok(digit);
}
}

Exercício: Avaliação de Expressões

Vamos escrever um interpretador recursivo simples para expressões aritméticas.

O tipo Box aqui é um ponteiro inteligente (smart pointer) e será abordado em detalhes mais adiante no curso. Uma expressão pode ser "encaixotada" com Box::new como visto nos testes. Para avaliar uma expressão encaixotada, use o operador de desreferência (*) para o "desencaixotar": eval(*boxed_expr).

Algumas expressões não podem ser avaliadas e retornarão um erro. O tipo padrão Result<Value, String> é um enum que representa um valor de sucesso (Ok(Value)) ou um erro (Err(String)). Abordaremos esse tipo em detalhes mais adiante.

Copie e cole o código no playground do Rust e comece a implementar eval. O produto final deve passar nos testes. Pode ser útil usar todo!() e fazer os testes passarem um por um. Você também pode ignorar um teste temporariamente com #[ignore]:

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

Se você terminar cedo, tente escrever um teste que resulte em divisão por zero ou integer overflow. Como você poderia lidar com isso com Result em vez de um pânico?

#![allow(unused)]
fn main() {
/// Uma operação a ser realizada em duas subexpressões.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Uma expressão, em forma de árvore.
#[derive(Debug)]
enum Expression {
    /// Uma operação em duas subexpressões.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Um 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("divisão por zero"))
    );
}
}

Solução

/// Uma operação a ser realizada em duas subexpressões.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// Uma expressão, em forma de árvore.
#[derive(Debug)]
enum Expression {
    /// Uma operação em duas subexpressões.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// Um 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("divisão por zero"));
                    } 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("divisão por zero"))
    );
}

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!("result: {:?}", eval(expr));
}

Métodos e Traits

This segment should take about 50 minutes. It contains:

Métodos

Rust permite que você associe funções aos seus novos tipos. Você faz isso com um bloco impl:

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

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

    // Empréstimo único com acesso de leitura e escrita em self
    fn add_lap(&mut self, lap: i32) {
        self.laps.push(lap);
    }

    // Empréstimo compartilhado com acesso apenas de leitura em self
    fn print_laps(&self) {
        println!("Registrou {} voltas para {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Volta {idx}: {lap} seg");
        }
    }

    // Propriedade exclusiva de self
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("Corrida {} foi encerrada, tempo total de voltas: {}", self.name, total);
    }
}

fn main() {
    let mut race = Race::new("Monaco Grand Prix");
    race.add_lap(70);
    race.add_lap(68);
    race.print_laps();
    race.add_lap(71);
    race.print_laps();
    race.finish();
    // race.add_lap(42);
}

Os argumentos self especificam o "receptor" - o objeto em que o método age. Existem vários receptores comuns para um método:

• &self: pega emprestado o objeto do chamador como uma referência compartilhada e imutável. O objeto pode ser usado novamente depois.
• &mut self: pega emprestado o objeto do chamador como uma referência única e mutável. O objeto pode ser usado novamente depois.
• self: toma posse do objeto e o move do chamador. O método se torna o proprietário do objeto. O objeto será descartado (desalocado) quando o método retorna, a menos que sua ownership (posse) seja explicitamente transmitida. Posse completa não significa automaticamente mutabilidade.
• mut self: o mesmo que acima, mas o método pode modificar o objeto.
• Sem receptor: isso se torna um método estático (static) no struct. Normalmente usado para criar construtores que, por convenção, são chamados new.

Traits

Rust permite abstrair características dos tipos usando trait. Eles são semelhantes a interfaces:

trait Pet {
    /// Retorna uma frase deste animal de estimação.
    fn talk(&self) -> String;

    /// Imprime uma string no terminal saudando este animal de estimação.
    fn greet(&self);
}

Implementando Traits

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

    fn greet(&self) {
        println!("Oh, você é adorável! Qual é o seu nome? {}", self.talk());
    }
}

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

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Auau, meu nome é {}", self.name)
    }
}

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

Supertraits

Um trait pode exigir que os tipos que o implementam também implementem outros traits, chamados supertraits. Aqui, qualquer tipo que implemente Pet deve 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!("{} tem {} pernas", puppy.name(), puppy.leg_count());
}

Tipos Associados

Tipos associados são tipos de espaço reservado que são fornecidos pela implementação do 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)));
}

Derivando

Os traits suportados podem ser implementados automaticamente para seus tipos personalizados, como segue:

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

fn main() {
    let p1 = Player::default(); // O _trait_ `Default` adiciona um construtor `default`.
    let mut p2 = p1.clone(); // O _trait_ `Clone` adiciona um método `clone`.
    p2.name = String::from("EldurScrollz");
    // O _trait_ `Debug` adiciona suporte para impressão com `{:?}`.
    println!("{:?} vs. {:?}", p1, p2);
}

Exercício: Trait de Logger

Vamos projetar um utilitário de registro (log) simples, usando um trait Logger com um método log. O código que pode registrar seu progresso pode então receber um &impl Logger. Nos testes, isso pode colocar mensagens no arquivo de log de teste, enquanto em uma compilação de produção, ele enviaria mensagens para um servidor de log.

No entanto, o StderrLogger fornecido abaixo registra todas as mensagens, independentemente da verbosidade. Sua tarefa é escrever um tipo VerbosityFilter que ignorará mensagens acima de uma verbosidade máxima.

Este é um padrão comum: uma struct que envolve uma implementação de trait e implementa esse mesmo trait, adicionando comportamento no processo. Que outros tipos de wrappers podem ser úteis em um utilitário de registro?

use std::fmt::Display;

pub trait Logger {
    /// Registra uma mensagem no nível de verbosidade fornecido.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

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

fn do_things(logger: &impl Logger) {
    logger.log(5, "PSC (_FYI_)");
    logger.log(2, "oh-oh");
}

// TODO: Definir e implementar `VerbosityFilter`.

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

Solução

use std::fmt::Display;

pub trait Logger {
    /// Registra uma mensagem no nível de verbosidade fornecido.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

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

fn do_things(logger: &impl Logger) {
    logger.log(5, "PSC (_FYI_)");
    logger.log(2, "oh-oh");
}

/// Registra apenas mensagens até o nível de verbosidade fornecido.
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);
}

Bem-vindos de volta

Including 10 minute breaks, this session should take about 3 hours and 15 minutes. It contains:

Genéricos (Generics)

This segment should take about 45 minutes. It contains:

Funções Genéricas

Rust suporta genéricos, o que permite abstrair algoritmos ou estruturas de dados (como ordenação ou uma árvore binária) sobre os tipos usados ou armazenados.

/// Escolhe `even` (par) ou `odd` (ímpar) dependendo do valor de `n`.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("escolheu um número: {:?}", pick(97, 222, 333));
    println!("escolheu uma tupla: {:?}", pick(28, ("cachorro", 1), ("gato", 2)));
}

Tipos de Dados Genéricos

Você pode usar genéricos para abstrair o tipo concreto do campo:

#[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:?} e {float:?}");
    println!("coords: {:?}", integer.coords());
}

Traits Genéricos

Traits também podem ser genéricos, assim como tipos e funções. Os parâmetros de um trait recebem tipos concretos quando ele é usado.

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

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("Convertido de inteiro: {from}"))
    }
}

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

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

Trait Bounds (Limites de Trait)

Ao trabalhar com genéricos, muitas vezes você exigir que os tipos implementem algum trait para poder utilizar os métodos do trait.

Você consegue fazer isso com T:Trait ou 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

Semelhante aos limites de trait, a sintaxe do trait impl pode ser usada em argumentos de funções e em valores de retorno:

// Código simplificado 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!("debuggable: {debuggable:?}");
}

dyn Trait

Além de usar traits para despacho estático via genéricos, o Rust também suporta usá-los para despacho dinâmico, apagamento de tipo, via 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!("Auau, meu nome é {}", self.name)
    }
}

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

// Usa genéricos e despacho estático.
fn generic(pet: &impl Pet) {
    println!("Olá, quem é você? {}", pet.talk());
}

// Usa apagamento de tipo e despacho dinâmico.
fn dynamic(pet: &dyn Pet) {
    println!("Olá, quem é você? {}", pet.talk());
}

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

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

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

Exercício: min Genérico

Neste exercício curto, você implementará uma função genérica min que determina o mínimo de dois valores, usando um trait LessThan.

use std::cmp::Ordering;

// TODO: implemente a função `min` usada em `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("olá", "até logo"), "até logo");
    assert_eq!(min("boi", "arara"), "arara");
}

Solução

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("olá", "até logo"), "até logo");
    assert_eq!(min("boi", "arara"), "arara");
}

Tipos da Biblioteca Padrão

This segment should take about 1 hour. It contains:

Biblioteca Padrão

Rust vem com uma biblioteca padrão (standard library) que ajuda a estabelecer um conjunto de tipos comuns usados por bibliotecas e programas Rust. Dessa forma, duas bibliotecas podem trabalhar juntas sem problemas porque ambas usam o mesmo tipo String.

Na verdade, o Rust contém várias camadas de Biblioteca Padrão: core, alloc e std.

• core inclui os tipos e funções mais básicos que não dependem de libc, alocador ou até mesmo a presença de um sistema operacional.
• alloc inclui tipos que requerem um alocador de heap global, tais como Vec, Box e Arc.
• Os aplicativos Rust embarcados geralmente usam apenas core e, às vezes, alloc.

Documentação

O Rust vem com uma extensa documentação. Por exemplo:

• Todos os detalhes sobre loops.
• Tipos primitivos como u8.
• Tipos da biblioteca padrão como Option ou BinaryHeap.

Na verdade, você pode documentar seu próprio código:

/// Determine se o primeiro argumento é divisível pelo segundo argumento.
///
/// Se o segundo argumento for zero, o resultado é falso.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

O conteúdo é tratado como Markdown. Todos os crates publicados na biblioteca Rust são documentados automaticamente em docs.rs utilizando a ferramenta rustdoc. É idiomático documentar todos os itens públicos em uma API usando este padrão.

Para documentar um item de dentro do item (como dentro de um módulo), use //! ou /*! .. */, chamado de "comentários de documentação interna":

//! Este módulo contém funcionalidades relacionadas à divisibilidade de inteiros.

Option

Já vimos algum uso de Option<T>. Ele armazena um valor do tipo T ou nada. Por exemplo, String::find retorna um Option<usize>.

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("find retornou {position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("find retornou {position:?}");
    assert_eq!(position.expect("Caractere não encontrado"), 0);
}

Result

Result é semelhante a Option, mas indica o sucesso ou falha de uma operação, cada um com um tipo diferente. Isso é genérico: Result<T, E> onde T é usado na variante Ok e E aparece na 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 diário: {contents} ({bytes} bytes)");
            } else {
                println!("Não foi possível ler o conteúdo do arquivo");
            }
        }
        Err(err) => {
            println!("Não foi possível abrir o diário: {err}");
        }
    }
}

String

String é uma string UTF-8 expansível:

fn main() {
    let mut s1 = String::new();
    s1.push_str("Olá");
    println!("s1: tam = {}, capacidade = {}", s1.len(), s1.capacity());

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

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

String implementa Deref<Target = str>, o que significa que você pode chamar todos os métodos de str em uma String.

Vec

Vec é o buffer padrão redimensionável alocado no heap:

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

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

    // Macro canônica para inicializar um vetor com elementos.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Mantém apenas os elementos pares.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Remove duplicatas consecutivas.
    v3.dedup();
    println!("{v3:?}");
}

Vec implementa Deref<Target = [T]>, o que significa que você pode chamar métodos de slice em um Vec.

HashMap

Hash map (Mapa de hash) padrão com proteção contra ataques HashDoS:

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Adventures of Huckleberry Finn", 207);
    page_counts.insert("Grimms' Fairy Tales", 751);
    page_counts.insert("Pride and Prejudice", 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "Nós sabemos sobre livros {}, mas não Les Misérables.",
            page_counts.len()
        );
    }

    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} páginas"),
            None => println!("{book} é desconhecido."),
        }
    }

    // Use o método .entry() para inserir um valor caso nada seja encontrado.
    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        let page_count: &mut i32 = page_counts.entry(book).or_insert(0);
        *page_count += 1;
    }

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

Exercício: Contador

Neste exercício, você usará uma estrutura de dados muito simples e a tornará genérica. Ela usa um std::collections::HashMap para acompanhar quais valores foram vistos e quantas vezes cada um apareceu.

A versão inicial de Counter é codificada para funcionar apenas para valores u32. Faça a estrutura e seus métodos genéricos sobre o tipo de valor sendo rastreado, dessa forma Counter pode rastrear qualquer tipo de valor.

Se você terminar cedo, tente usar o método entry para reduzir pela metade o número de pesquisas de hash necessárias para implementar o método count.

use std::collections::HashMap;

/// Counter conta o número de vezes que cada valor do tipo T foi visto.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Cria um novo Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Conta uma ocorrência do valor fornecido.
    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);
        }
    }

    /// Retorna o número de vezes que o valor fornecido foi visto.
    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!("viu {} valores iguais a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("obteve {} maçãs", strctr.times_seen("apple"));
}

Solução

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

/// Counter conta o número de vezes que cada valor do tipo T foi visto.
struct Counter<T> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Cria um novo Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Conta uma ocorrência do valor fornecido.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Retorna o número de vezes que o valor fornecido foi visto.
    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!("viu {} valores iguais a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("obteve {} maçãs", strctr.times_seen("apple"));
}

Traits da Biblioteca Padrão

This segment should take about 1 hour and 10 minutes. It contains:

Comparações

Esses traits suportam comparações entre valores. Todos os traits podem ser derivados para tipos que contêm campos que implementam esses traits.

PartialEq e Eq

PartialEq é uma relação de equivalência parcial, com o método eq obrigatório e o método ne fornecido. Os operadores == e != chamarão esses métodos.

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

Eq é uma relação de equivalência completa (reflexiva, simétrica e transitiva) e implica PartialEq. Funções que exigem equivalência completa usarão Eq como um limite de trait.

PartialOrd e Ord

PartialOrd define uma ordenação parcial, com um método partial_cmp. Ele é usado para implementar os operadores <, <=, >= e >.

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 é uma ordenação total, com cmp retornando Ordering.

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

Operadores

A sobrecarga de operadores é implementada por meio do trait contido em 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

Os tipos implementam From e Into para facilitar as conversões de tipo:

fn main() {
    let s = String::from("olá");
    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 é implementado automaticamente quando From é implementado:

fn main() {
    let s: String = "olá".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}");
}

Conversões

O Rust não tem conversões de tipo implícitas, mas suporta conversões explícitas com as. Essas geralmente seguem a semântica de C onde elas são definidas.

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

Os resultados de as são sempre definidos no Rust e consistentes em todas as plataformas. Isso pode não corresponder à sua intuição para alterar o sinal ou converter para um tipo menor - verifique a documentação e comente

Converter com as é uma ferramenta relativamente afiada que é fácil de usar incorretamente e pode ser uma fonte de bugs sutis à medida que o trabalho de manutenção futuro altera os tipos que são usados ou os intervalos de valores nos tipos. As conversões são melhores usadas apenas quando a intenção é indicar truncamento incondicional (por exemplo, selecionar os 32 bits inferiores de um u64 com as u32, independentemente do que estava nos bits altos).

Para conversões infalíveis (por exemplo, u32 para u64), prefira usar From ou Into em vez de as para confirmar que a conversão é de fato infalível. Para conversões falíveis, TryFrom e TryInto estão disponíveis quando você deseja lidar com conversões que se encaixam de maneira diferente daquelas que não se encaixam.

Read e Write

Usando Read e BufRead, você pode abstrair as fontes de dados do tipo 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!("linhas na _slice_: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("linhas no arquivo: {}", count_lines(file));
    Ok(())
}

Da mesma forma, Write permite abstrair a escrita de dados do tipo 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, "Olá")?;
    log(&mut buffer, "Mundo")?;
    println!("Registrado: {:?}", buffer);
    Ok(())
}

O Trait Default

O trait Default fornece uma implementação padrão para um 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: "Y está definido!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

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

Closures

Closures ou expressões lambda têm tipos que não podem ser nomeados. No entanto, eles implementam os traits especiais Fn, FnMut e FnOnce:

fn apply_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {
    println!("Chamando a função com {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("Olá".to_string());
    hi("Greg");
}

Exercício: ROT13

Neste exemplo, você implementará o clássico cifra "ROT13". Copie este código para o playground e implemente as partes que faltam. Apenas rotacione caracteres alfabéticos ASCII para garantir que o resultado ainda seja UTF-8 válido.

use std::io::Read;

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

// Implemente o 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());
            }
        }
    }
}

O que acontece se você encadear duas instâncias de RotDecoder, cada uma rotacionando 13 caracteres?

Solução

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());
            }
        }
    }
}

Bem-vindos ao Dia 3

Hoje, vamos cobrir:

• Gerenciamento de memória, tempos de vida (lifetimes) e o verificador de empréstimo (borrow checker): como o Rust garante a segurança da memória.
• Ponteiros inteligentes (smart pointers): tipos de ponteiros da biblioteca padrão.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

Gerenciamento de Memória

This segment should take about 1 hour. It contains:

Revisão da Memória de Programa

Os programas alocam memória de duas maneiras:

• Pilha: Área contínua de memória para variáveis locais.

  • Os valores têm tamanhos fixos conhecidos em tempo de compilação.
  • Extremamente rápida: basta mover um ponteiro de pilha.
  • Fácil de gerenciar: segue chamadas de função.
  • Ótima localidade de memória.

• Heap: Armazenamento de valores fora das chamadas de função.

  • Valores possuem tamanhos dinâmicos determinados em tempo de execução.
  • Ligeiramente mais devagar que a pilha: é necessário um pouco de gerenciamento.
  • Sem garantias de localidade de memória.

Exemplo

A criação de uma String coloca metadados de tamanho fixo na pilha e dados dinamicamente dimensionados - a string propriamente dita - no heap:

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

fn main() {
    let mut s1 = String::from("Olá");
    s1.push(' ');
    s1.push_str("mundo");
    // NÃO FAÇA ISSO EM CASA! Somente com propósito educacional.
    // String não fornece nenhuma garantia sobre o seu layout, então isso pode causar
    // um comportamento indefinido.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacidade = {capacity}, ptr = {ptr:#x}, compr = {len}");
    }
}

Abordagens para Gerenciamento de Memória

Tradicionalmente, as linguagens se dividem em duas grandes categorias:

• Controle total através do gerenciamento manual de memória: C, C++, Pascal, ...
  • Programador decide quando alocar ou liberar memória do heap.
  • Programador deve determinar se um ponteiro ainda aponta para uma memória válida.
  • Estudos mostram que os programadores cometem erros.
• Segurança total através do gerenciamento automático de memória em tempo de execução: Java, Python, Go, Haskell, ...
  • Um sistema em tempo de execução garante que a memória não seja liberada até que não possa mais ser referenciada.
  • Normalmente implementado com contagem de referência, coleta de lixo ou RAII.

Rust oferece uma nova combinação:

Controle total e segurança por imposição do correto gerenciamento de memória em tempo de compilação.

Ele faz isso com um conceito de ownership (posse) explícito.

Ownership

Todas as associações de variáveis têm um escopo onde são válidas e é um erro usar uma variável fora de seu escopo:

struct Point(i32, i32);

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

Dizemos que a variável owns (possui) o valor. Todo valor em Rust tem precisamente um owner (dono) em todos os momentos.

No final do escopo, a variável é descartada e os dados são liberados. Um destrutor pode ser executado aqui para liberar recursos.

Semântica de Movimento

Uma atribuição transferirá o ownership entre variáveis:

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

• A atribuição de s1 a s2 transfere o ownership.
• Quando s1 sai do escopo, nada acontece: ele não tem ownership.
• Quando s2 sai do escopo, os dados da string são liberados.

Antes de mover para s2:

Depois de mover para s2:

Quando você passa um valor para uma função, o valor é atribuído ao parâmetro da função. Isso transfere a ownership:

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

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

std::string s1 = "Cpp";
std::string s2 = s1;  // Duplica os dados em s1.

Clone

Às vezes você quer fazer uma cópia de um valor. O trait Clone consegue isso.

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

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

Tipos Copiáveis

Embora a semântica de movimento seja o padrão, certos tipos são copiados por padrão:

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

Esses tipos implementam o trait Copy.

Você pode habilitar seus próprios tipos para usar a semântica de cópia:

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

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

• Após a atribuição, tanto p1 quanto p2 possuem seus próprios dados.
• Também podemos usar p1.clone() para copiar os dados explicitamente.

O Trait Drop

Valores que implementam Drop podem especificar o código a ser executado quando saem do escopo:

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Descartando {}", 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!("Saindo do bloco B");
        }
        println!("Saindo do bloco A");
    }
    drop(a);
    println!("Saindo do main");
}

Exercício: Tipo Builder

Neste exemplo, implementaremos um tipo de dados complexo que possui todos os seus dados. Usaremos o "builder pattern" para suportar a construção de um novo valor peça por peça, usando funções de conveniência.

Preencha as peças que faltam.

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

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

/// Uma representação de um pacote de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Retorna uma representação deste pacote como uma dependência, para uso na
    /// construção de outros pacotes.
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// Um construtor para um Pacote. Use `build()` para criar o próprio `Package`.
struct PackageBuilder(Package);

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

    /// Define a versão do pacote.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

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

    /// Adiciona uma dependência adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Define a linguagem. Se não definida, a linguagem é 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!("log: {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:?}");
}

Solução

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

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

/// Uma representação de um pacote de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Retorna uma representação deste pacote como uma dependência, para uso na
    /// construção de outros pacotes.
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// Um construtor para um Pacote. Use `build()` para criar o próprio `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 a versão do pacote.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Define os autores do pacote.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Adiciona uma dependência adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Define a linguagem. Se não definida, a linguagem é 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!("log: {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:?}");
}

Ponteiros Inteligentes (Smart Pointers)

This segment should take about 55 minutes. It contains:

Box<T>

Box é um ponteiro owned para dados no heap:

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

Box<T> implementa Deref<Target = T>, o que significa que você pode chamar métodos de T diretamente em um Box<T>.

Tipos de dados recursivos ou tipos de dados com tamanhos dinâmicos precisam usar uma Box:

#[derive(Debug)]
enum List<T> {
    /// Uma lista não vazia: primeiro elemento e o resto da lista.
    Element(T, Box<List<T>>),
    /// Uma lista vazia.
    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("Apenas 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!("Tamanho de just_box: {}", size_of_val(&just_box));
    println!("Tamanho de optional_box: {}", size_of_val(&optional_box));
    println!("Tamanho de none: {}", size_of_val(&none));
}

Rc

Rc é um ponteiro compartilhado com contagem de referência. Use-o quando precisar consultar os mesmos dados a partir de vários locais:

use std::rc::Rc;

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

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

• Veja Arc e Mutex se você estiver em um contexto multi-thread.
• Você pode demover (downgrade) um ponteiro compartilhado para um ponteiro Weak (fraco) para criar ciclos que serão descartados.

Objetos de Trait Proprietários

Anteriormente vimos como objetos de trait podem ser usados com referências, por exemplo, &dyn Pet. No entanto, também podemos usar objetos de trait com ponteiros inteligentes como Box para criar um objeto de trait owned: 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!("Auau, meu nome é {}", 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("Bidu"), age: 5 }),
    ];
    for pet in pets {
        println!("Olá, quem é você? {}", pet.talk());
    }
}

Layout da memória após alocar pets:

Exercício: Árvore Binária

Uma árvore binária é uma estrutura de dados do tipo árvore onde cada nó tem dois filhos (esquerdo e direito). Criaremos uma árvore onde cada nó armazena um valor. Para um determinado nó N, todos os nós na subárvore esquerda de N contêm valores menores, e todos os nós na subárvore direita de N conterão valores maiores.

Implemente os seguintes tipos, para que os testes fornecidos passem.

Extra: implemente um iterador sobre uma árvore binária que retorna os valores em ordem.

/// Um nó na árvore binária.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Uma subárvore possivelmente vazia.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Um contêiner que armazena um conjunto de valores, usando uma árvore binária.
///
/// Se o mesmo valor for adicionado várias vezes, ele é armazenado apenas uma 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()
    }
}

// Implemente `new`, `insert`, `len` e `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); // não é um item ú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));
    }
}

Solução

use std::cmp::Ordering;

/// Um nó na árvore binária.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Uma subárvore possivelmente vazia.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Um contêiner que armazena um conjunto de valores, usando uma árvore binária.
///
/// Se o mesmo valor for adicionado várias vezes, ele é armazenado apenas uma 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); // não é um item ú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));
    }
}

Bem-vindos de volta

Including 10 minute breaks, this session should take about 1 hour and 55 minutes. It contains:

Empréstimo (Borrowing)

This segment should take about 55 minutes. It contains:

Emprestando um Valor

Como vimos antes, ao invés de transferir a ownership ao chamar uma função, você pode deixar uma função emprestar (borrow) o 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:?}");
}

• A função add pega emprestado (borrows) dois pontos e retorna um novo ponto.
• O chamador mantém a ownership das entradas.

Verificação de Empréstimo

O verificador de empréstimo (borrow checker) do Rust impõe restrições sobre as maneiras como você pode emprestar valores. Para um determinado valor, a qualquer momento:

• Você pode ter uma ou mais referências compartilhadas para o valor, ou
• Você pode ter exatamente uma referência exclusiva para o 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}");
}

Erros de Empréstimo

Como um exemplo concreto de como essas regras de empréstimo evitam erros de memória, considere o caso de modificar uma coleção enquanto há referências para os seus elementos:

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

Da mesma forma, considere o caso de invalidação do iterador:

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

Mutabilidade Interior

Em algumas situações, é necessário modificar dados atrás de uma referência compartilhada (somente leitura). Por exemplo, uma estrutura de dados compartilhada pode ter um cache interno e desejar atualizar esse cache a partir de métodos somente leitura.

O padrão de "mutabilidade interna" permite acesso exclusivo (mutável) por trás de uma referência compartilhada. A biblioteca padrão fornece várias maneiras de fazer isso, garantindo segurança, geralmente realizando uma verificação em tempo de execução.

RefCell

use std::cell::RefCell;

fn main() {
    // Observe que `cell` NÃO é declarado como mutável.
    let cell = RefCell::new(5);

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

        // Isso gera um erro em tempo de execução.
        // let other = cell.borrow();
        // println!("{}", *other);
    }

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

Cell

Cell envolve um valor e permite obter ou definir o valor, mesmo com uma referência compartilhada para o Cell. No entanto, não permite nenhuma referência ao valor. Como não há referências, as regras de empréstimo não podem ser quebradas.

use std::cell::Cell;

fn main() {
    // Observe que `cell` NÃO é declarado como mutável.
    let cell = Cell::new(5);

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

Exercício: Estatísticas de Saúde

Você está trabalhando na implementação de um sistema de monitoramento de saúde. Como parte disso, você precisa acompanhar as estatísticas de saúde dos usuários.

Você começará com um esboço de função em um bloco impl e também uma definição de struct User. Seu objetivo é implementar o método esboçado na struct User definida no bloco impl.

Copie o código abaixo em https://play.rust-lang.org/ e implemente os métodos que estão faltando:

// TODO: remova isto quando você terminar sua implementação.
#![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!("Atualiza as estatísticas de um usuário com base nas medições de uma visita ao médico")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("Eu sou {} e minha idade é {}", 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)));
}

Solução

#![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!("Eu sou {} e minha idade é {}", 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)));
}

Tempos de Vida (Lifetimes)

This segment should take about 50 minutes. It contains:

Anotações de Tempo de Vida

Uma referência tem um tempo de vida (lifetime), que não deve "sobreviver" ao valor ao qual se refere. Isso é verificado pelo borrow checker (verificador de empréstimo).

O tempo de vida pode ser implícito - isso é o que vimos até agora. Os tempos de vida também podem ser explícitos: &'a Point, &'document str. Os tempos de vida começam com ' e 'a é um nome padrão típico. Leia &'a Point como "um Point emprestado que é válido por pelo menos o tempo de vida a".

Os tempos de vida são sempre inferidos pelo compilador: você não pode atribuir um tempo de vida por conta própria. Anotações explícitas de tempo de vida criam restrições onde há ambiguidade; o compilador verifica se há uma solução válida.

Os tempos de vida se tornam mais complicados ao considerar a passagem de valores para e a devolução de valores de funções.

#[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); // Qual é o tempo de vida de p3?
    println!("p3: {p3:?}");
}

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

Tempos de vida (Lifetimes) em Chamadas de Função

Tempos de vida para argumentos de função e valores de retorno precisam ser completamente especificados, mas o Rust permite que eles sejam omitidos na maioria das vezes com algumas regras simples. Isso não é inferência - é apenas uma abreviação sintática.

• Cada argumento que não tem uma anotação de tempo de vida é dado um.
• Se houver apenas um tempo de vida de argumento, ele é dado a todos os valores de retorno não anotados.
• Se houver vários tempos de vida de argumento, mas o primeiro for para self (self), esse tempo de vida é dado a todos os valores de retorno não 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> {

Tempos de Vida em Estruturas de Dados

Se um tipo de dados armazena dados emprestados, ele deve ser anotado com um tempo de vida:

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

fn erase(text: String) {
    println!("Até logo {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

Exercício: Análise de Protobuf

Neste exercício, você construirá um analisador (parser) para a codificação binária de protobuf. Não se preocupe, é mais simples do que parece! Isso ilustra um padrão de análise comum, passando slices de dados. Os próprios dados subjacentes nunca são copiados.

Analisar (parse) completamente uma mensagem protobuf requer conhecer os tipos dos campos, indexados por seus números de campo. Isso é normalmente fornecido em um arquivo proto. Neste exercício, codificaremos essas informações em declarações match em funções que são chamadas para cada campo.

Usaremos o seguinte proto:

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

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

Uma mensagem proto é codificada como uma série de campos, um após o outro. Cada um é implementado como uma "tag" seguida pelo valor. A tag contém um número de campo (por exemplo, 2 para o campo id de uma mensagem Person) e um tipo de fio (wire type) definindo como a carga útil deve ser determinada a partir do fluxo (stream) de bytes.

Números inteiros, incluindo a tag, são representados com uma codificação de comprimento variável chamada VARINT. Felizmente, parse_varint é definido para você abaixo. O código fornecido também define callbacks para lidar com campos Person e PhoneNumber, e para analisar uma mensagem em uma série de chamadas para esses callbacks.

O que resta para você é implementar a função parse_field e o trait ProtoMessage para Person e PhoneNumber.

/// Um wire type como visto no wire.
enum WireType {
    /// O Varint WireType indica que o valor é um único VARINT.
    Varint,
    //I64,  -- não é necessário para este exercício
    /// O Len WireType indica que o valor é um comprimento representado como um
    /// VARINT seguido exatamente por esse número de bytes.
    Len,
    /// O I32 WireType indica que o valor é precisamente 4 bytes em
    /// ordem little-endian contendo um inteiro de 32 bits com sinal.
    I32,
}

#[derive(Debug)]
/// O valor de um campo, digitado com base no wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- não é necessário para este exercício
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Um campo, contendo o número do campo e seu valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    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,  -- não é necessário para este exercício
            2 => WireType::Len,
            5 => WireType::I32,
            _ => panic!("Wire-type inválido: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Esperava-se que a string fosse um campo `Len`");
        };
        std::str::from_utf8(data).expect("String inválida")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Esperava-se que os bytes fossem um campo `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Esperava-se que `u64` fosse um campo `Varint");
        };
        *value
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("Esperava-se que `i32` fosse um campo `I32");
        };
        *value
    }
}

/// Analise (_parse_) um VARINT, retornando o valor analisado e os bytes restantes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Não há bytes suficientes para o varint");
        };
        if b & 0x80 == 0 {
            // Este é o último byte do VARINT, então converta-o para
            // um u64 e retorne-o.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Mais de 7 bytes é inválido.
    panic!("Bytes demais para varint");
}

/// Converta uma tag em um número de campo e um WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}


/// Analise (_parse_) um campo, retornando os 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!("Com base no wire type, construa um Field, consumindo quantos bytes forem necessários.")
    };
    todo!("Retorne o campo e quaisquer bytes não consumidos.")
}

/// Analise (_parse_) uma mensagem nos dados fornecidos, chamando `T::add_field` para cada campo na
/// mensagem.
///
/// Todo o input é consumido.
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>>,
}

// TODO: Implemente ProtoMessage para Person e 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);
}

Solução

/// Um wire type como visto no wire.
enum WireType {
    /// O Varint WireType indica que o valor é um único VARINT.
    Varint,
    //I64,  -- não é necessário para este exercício
    /// O Len WireType indica que o valor é um comprimento representado como um
    /// VARINT seguido exatamente por esse número de bytes.
    Len,
    /// O I32 WireType indica que o valor é precisamente 4 bytes em
    /// ordem little-endian contendo um inteiro de 32 bits com sinal.
    I32,
}

#[derive(Debug)]
/// O valor de um campo, digitado com base no wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- não é necessário para este exercício
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Um campo, contendo o número do campo e seu valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    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,  -- não é necessário para este exercício
            2 => WireType::Len,
            5 => WireType::I32,
            _ => panic!("Wire-type inválido: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Esperava-se que a string fosse um campo `Len`");
        };
        std::str::from_utf8(data).expect("String inválida")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Esperava-se que os bytes fossem um campo `Len`");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Esperava-se que `u64` fosse um campo `Varint");
        };
        *value
    }

    #[allow(dead_code)]
    fn as_i32(&self) -> i32 {
        let FieldValue::I32(value) = self else {
            panic!("Esperava-se que `i32` fosse um campo `I32");
        };
        *value
    }
}

/// Analise (_parse_) um VARINT, retornando o valor analisado e os bytes restantes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Não há bytes suficientes para o varint");
        };
        if b & 0x80 == 0 {
            // Este é o último byte do VARINT, então converta-o para
            // um u64 e retorne-o.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // Mais de 7 bytes é inválido.
    panic!("Bytes demais para varint");
}

/// Converta uma tag em um número de campo e um WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}

/// Analise (_parse_) um campo, retornando os 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 não é um `usize` válido");
            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);
            // Unwrap o erro porque `value` definitivamente tem 4 bytes.
            let value = i32::from_le_bytes(value.try_into().unwrap());
            (FieldValue::I32(value), remainder)
        }
    };
    (Field { field_num, value: fieldvalue }, remainder)
}

/// Analise (_parse_) uma mensagem nos dados fornecidos, chamando `T::add_field` para cada campo na
/// mensagem.
///
/// Todo o input é consumido.
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())),
            _ => {} // pule todo o resto
        }
    }
}

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(),
            _ => {} // pule todo o resto
        }
    }
}

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);
}

Bem-vindos ao Dia 4

Hoje abordaremos tópicos relacionados à construção de software em larga escala em Rust:

• Iteradores: uma análise profunda do trait Iterator.
• Módulos e visibilidade.
• Testes.
• Tratamento de erros: pânicos, Result e o operador ?.
• Rust inseguro: a saída de emergência quando você não consegue se expressar em Rust seguro.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 40 minutes. It contains:

Iteradores

This segment should take about 45 minutes. It contains:

Iterator

O trait Iterator suporta a iteração sobre valores em uma coleção. Ele requer um método next e fornece muitos métodos. Muitos tipos da biblioteca padrão implementam Iterator, e você também pode implementá-lo:

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

O trait Iterator informa como iterar depois de criar um iterador. O trait relacionado IntoIterator define como criar um iterador para um tipo. Ele é usado automaticamente pelo laço 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!("point = {x}, {y}");
    }
}

FromIterator

FromIterator permite que você construa uma coleção a partir de um 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

Exercício: Encadeamento de Métodos de Iterador

Neste exercício, você precisará encontrar e usar alguns dos métodos fornecidos no trait Iterator para implementar um cálculo complexo.

Copie o seguinte código para https://play.rust-lang.org/ e faça os testes passarem. Use uma expressão de iterador e collect o resultado para construir o valor de retorno.

#![allow(unused)]
fn main() {
/// Calcule as diferenças entre os elementos de `values` deslocados por `offset`,
/// voltando ao início de `values` no final.
///
/// O elemento `n` do resultado é `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![]);
}
}

Solução

/// Calcule as diferenças entre os elementos de `values` deslocados por `offset`,
/// voltando ao início de `values` no final.
///
/// O elemento `n` do resultado é `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

This segment should take about 40 minutes. It contains:

Módulos

Vimos como os blocos impl nos permitem usar namespaces (espaços de nomes) de funções para um tipo.

Da mesma forma, mod nos permite usar namespaces de tipos e funções:

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

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

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

Hierarquia do Sistema de Arquivos

Omitir o conteúdo do módulo dirá ao Rust para procurá-lo em outro arquivo:

mod garden;

Isto diz ao Rust que o conteúdo do módulo garden é encontrado em src/garden.rs. Da mesma forma, um módulo garden::vegetables pode ser encontrado em src/garden/vegetables.rs.

A raiz do crate está em:

• src/lib.rs (para um crate de biblioteca)
• src/main.rs (para um crate binário)

Módulos definidos em arquivos também podem ser documentados usando "comentários internos de documento" (inner doc comments). Estes documentam o item que os contém - neste caso, um módulo.

//! Este módulo implementa o jardim (_garden_), incluindo uma implementação de germinação
//!  de alto desempenho.

// Re-exporta tipos deste módulo.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Semeia os pacotes de semente fornecidos.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Colhe os vegetais no jardim que está pronto.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

Visibilidade

Módulos são limitadores de privacidade:

• Itens do módulo são privados por padrão (ocultam detalhes de implementação).
• Itens paternos e fraternos são sempre visíveis.
• Em outras palavras, se um item é visível no módulo foo, ele é visível em todos os descendentes 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

Um módulo pode trazer símbolos de outro módulo para o escopo com use. Normalmente, você verá algo assim na parte superior de cada módulo:

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

Caminhos (Paths)

Caminhos são resolvidos da seguinte forma:

1. Como um caminho relativo:

   • foo ou self::foo referem-se à foo no módulo atual,
   • super::foo refere-se à foo no módulo pai.

2. Como um caminho absoluto:

   • crate::foo refere-se à foo na raiz do crate atual,
   • bar::foo refere-se a foo no crate bar.

Exercício: Módulos para uma Biblioteca GUI

Neste exercício, você reorganizará uma pequena implementação de uma biblioteca GUI. Esta biblioteca define um trait Widget e algumas implementações desse trait, bem como uma função main.

É típico colocar cada tipo ou conjunto de tipos intimamente relacionados em seu próprio módulo, então cada tipo de widget deve ter seu próprio módulo.

Configuração do Cargo

O playground do Rust suporta apenas um arquivo, então você precisará criar um projeto Cargo em seu sistema de arquivos local:

cargo init gui-modules
cd gui-modules
cargo run

Edite o src/main.rs resultante para adicionar declarações mod, e adicione arquivos adicionais no diretório src.

Código-fonte

Aqui está a implementação de um único módulo da biblioteca GUI:

pub trait Widget {
    /// Largura natural de `self`.
    fn width(&self) -> usize;

    /// Desenha o _widget_ em um buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Desenha o _widget_ na saída padrão.
    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 {
        // Adiciona 4 preenchimentos para as bordas
        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();

        // TODO: Altere draw_into para retornar Result<(), std::fmt::Error>. Então use
        // o operador ? aqui em vez 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 // adicione um pouco de preenchimento
    }

    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("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("Este é um pequeno demo de GUI em texto.")));
    window.add_widget(Box::new(Button::new("Clique em mim!")));
    window.draw();
}

Solução

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// Largura natural de `self`.
    fn width(&self) -> usize;

    /// Desenha o _widget_ em um buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Desenha o _widget_ na saída padrão.
    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 // adicione um pouco de preenchimento
    }

    // 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
        // Adiciona 4 preenchimentos para as bordas
        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();

        // TODO: depois de aprender sobre tratamento de erros, você pode alterar
        // draw_into para retornar Result<(), std::fmt::Error>. Então use
        // o operador ? aqui em vez 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("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("Este é um pequeno demo de GUI em texto.")));
    window.add_widget(Box::new(widgets::Button::new("Clique em mim!")));
    window.draw();
}

Testes

This segment should take about 45 minutes. It contains:

Testes Unitários

Rust e Cargo vêm com uma estrutura de testes unitários simples:

• Testes unitários são suportados em todo o seu código.

• Testes de integração são suportados através do diretório tests/.

Testes são marcados com #[test]. Testes unitários são frequentemente colocados em um módulo aninhado tests, usando #[cfg(test)] para compilá-los condicionalmente apenas ao construir testes.

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("Olá"), "Olá");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Hello World"), "Olá");
    }
}

• Isso permite que você tenha testes unitários auxiliares privados.
• O atributo #[cfg(test)] somente fica ativo quando você executa cargo test.

Outros Tipos de Testes

Testes de Integração

Se quiser testar sua biblioteca como um cliente, use um teste de integração.

Crie um arquivo .rs em tests/:

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

Esses testes têm acesso somente à API pública do seu crate.

Testes de Documentação

Rust tem suporte embutido para testes de documentação:

#![allow(unused)]
fn main() {
/// Reduz uma string para o comprimento fornecido.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• Blocos de código em comentários /// são vistos automaticamente como código Rust.
• O código será compilado e executado como parte do cargo test.
• Adicionar # no código o ocultará da documentação, mas ainda o compilará/executará.
• Teste o código acima no Rust Playground.

Lints do Compilador e Clippy

O compilador Rust produz mensagens de erro fantásticas, bem como alertas/lints úteis embutidos. Clippy fornece ainda mais lints, organizados em grupos que podem ser habilitados por projeto.

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X provavelmente cabe em um u16, certo? {}", x as u16);
}

Exercício: Algoritmo de Luhn

Algoritmo de Luhn

O algoritmo de Luhn é usado para validar números de cartão de crédito. O algoritmo recebe uma string como entrada e faz o seguinte para validar o número do cartão de crédito:

• Ignore todos os espaços. Rejeite números com menos de dois dígitos.

• Movendo-se da direita para a esquerda, dobre cada segundo dígito: para o número 1234, dobramos 3 e 1. Para o número 98765, dobramos 6 e 8.

• Depois de dobrar um dígito, some os dígitos se o resultado for maior que 9. Então, dobrar 7 se torna 14 que se torna 1 + 4 = 5.

• Some todos os dígitos, dobrados ou não.

• O número do cartão de crédito é válido se a soma terminar em 0.

O código fornecido provê uma implementação com bugs do algoritmo de Luhn, junto com dois testes unitários básicos que confirmam que a maior parte do algoritmo é implementada corretamente.

Copie o código abaixo para https://play.rust-lang.org/ e escreva testes adicionais para descobrir bugs na implementação fornecida, corrigindo quaisquer bugs que você encontrar.

#![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"));
    }
}
}

Solução

// Esta é a versão com bugs que aparece no 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 é a solução e passa em todos os testes abaixo.
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!(
        "O número do cartão de crédito {cc_number} é válido? {}",
        if luhn(cc_number) { "sim" } else { "não" }
    );
}

#[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 "));
    }
}

Bem-vindos de volta

Including 10 minute breaks, this session should take about 2 hours and 15 minutes. It contains:

Tratamento de Erros

This segment should take about 1 hour. It contains:

Pânicos (Panics)

Rust lida com erros fatais com um "pânico".

O Rust irá disparar um panic (pânico) se um erro fatal ocorrer em tempo de execução:

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• Pânicos são para erros irrecuperáveis e inesperados.
  • Pânicos são sintomas de bugs no programa.
  • Falhas em tempo de execução como verificações de limites falhadas podem disparar um pânico
  • Asserções (como assert!) disparam um pânico em caso de falha
  • Pânicos com moticos específicos podem usar a macro panic!.
• Um pânico irá "desenrolar" a pilha, descartando valores como se as funções tivessem retornado.
• Use APIs que não disparam erros do tipo pânico (como Vec::get) se não for aceitável o travamento do programa.

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "Nenhum problema aqui!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("ah não!");
    });
    println!("{result:?}");
}

Result

Nosso mecanismo primário para tratamento de erros em Rust é o enum Result, que vimos brevemente ao discutir tipos da biblioteca padrão.

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 diário: {contents} ({bytes} bytes)");
            } else {
                println!("Não foi possível ler o conteúdo do arquivo");
            }
        }
        Err(err) => {
            println!("Não foi possível abrir o diário: {err}");
        }
    }
}

Operador Try

Erros em tempo de execução como conexão recusada ou arquivo não encontrado são tratados com o tipo Result, mas combinar esse tipo em cada chamada pode ser complicado. O operador ? é usado para retornar erros ao chamador. Ele permite que você transforme o comum

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

no muito mais simples

some_expression?

Podemos usar isso para simplificar nosso código de tratamento de erros:

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!("username ou erro: {username:?}");
}

Conversões Try

A expansão efetiva do operador ? é um pouco mais complicada do que indicado anteriormente:

expression?

funciona da mesma forma que

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

A chamada From::from aqui significa que tentamos converter o tipo de erro para o tipo retornado pela função. Isso torna fácil encapsular erros em erros de nível superior.

Exemplo

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, "Erro E/S: {e}"),
            Self::EmptyUsername(path) => write!(f, "Nome de usuário não encontrado em {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!("username ou erro: {username:?}");
}

Tipos de Erros Dinâmicos

Às vezes, queremos permitir que qualquer tipo de erro seja retornado sem escrever nosso próprio enum cobrindo todas as possibilidades diferentes. O trait std::error::Error torna fácil criar um objeto trait que pode conter qualquer erro.

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!("Contagem: {count}"),
        Err(err) => println!("Erro: {err}"),
    }
}

thiserror e anyhow

Os crates thiserror e anyhow são amplamente utilizados para simplificar o tratamento de erros.

• thiserror é frequentemente usado em bibliotecas para criar tipos de erro personalizados que implementam From<T>.
• anyhow é frequentemente usado por aplicações para ajudar no tratamento de erros em funções, incluindo adicionar informações contextuais aos seus erros.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Nome de usuário não encontrado em {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!("Falha ao abrir {path}"))?
        .read_to_string(&mut username)
        .context("Falha ao ler")?;
    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!("Nome do usuário: {username}"),
        Err(err) => println!("Erro: {err:?}"),
    }
}

Exercício: Reescrevendo com Result

O seguinte implementa um analisador muito simples para uma linguagem de expressão. No entanto, ele lida com erros disparando um pânico. Reescreva-o para usar o tratamento de erros idiomático e propagar erros para um retorno de main. Sinta-se à vontade para usar thiserror e anyhow.

DICA: comece corrigindo o tratamento de erros na função parse. Depois que isso estiver funcionando corretamente, atualize Tokenizer para implementar Iterator<Item=Result<Token, TokenizerError>> e trate isso no analisador (parser).

use std::iter::Peekable;
use std::str::Chars;

/// Um operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Um token na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Uma expressão na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Uma referência a uma variável.
    Var(String),
    /// Um número literal.
    Number(u32),
    /// Uma operação binária.
    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!("Caractere 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!("Fim de entrada inesperado");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Inteiro de 32 bits inválido'");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Token inesperado {tok:?}"),
        };
        // Olhe adiante para analisar uma operação binária, se presente.
        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:?}");
}

Solução

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// Um operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Um token na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Uma expressão na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Uma referência a uma variável.
    Var(String),
    /// Um número literal.
    Number(u32),
    /// Uma operação binária.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Caractere '{0}' inesperado na 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("Erro de tokenizador: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Fim de entrada inesperado")]
    UnexpectedEOF,
    #[error("Token inesperado {0:?}")]
    UnexpectedToken(Token),
    #[error("Número invá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)),
        };
        // Olhe adiante para analisar uma operação binária, se presente.
        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(())
}

Rust Inseguro (Unsafe)

This segment should take about 1 hour and 5 minutes. It contains:

Rust Inseguro (Unsafe)

A linguagem Rust tem duas partes:

• Rust Seguro (Safe): memória segura, nenhum comportamento indefinido é possível.
• Rust Inseguro (Unsafe): pode desencadear comportamento indefinido se pré-condições forem violadas.

Veremos principalmente Rust seguro neste curso, mas é importante saber o que é Rust inseguro.

Código inseguro é geralmente pequeno e isolado, e seu funcionamento correto deve ser cuidadosamente documentado. Geralmente é envolto em uma camada de abstração segura.

O código inseguro do Rust oferece acesso a cinco novos recursos:

• Desreferenciar ponteiros brutos (raw pointers).
• Acessar ou modificar variáveis estáticas mutáveis.
• Acessar os campos de uma union.
• Chamar funções unsafe (inseguras), incluindo funções extern (externas).
• Implementar traits unsafe.

A seguir, abordaremos brevemente os recursos inseguros. Para detalhes completos, consulte o Capítulo 19.1 no Rust Book e o Rustonomicon.

Desreferenciando Ponteiros Brutos

Criar ponteiros é seguro, mas desreferenciá-los requer unsafe:

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

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // SEGURANÇA: r1 e r2 foram obtidos através de referências e logo é
    // garantido que eles não sejam nulos e sejam propriamente alinhados, os objetos
    // cujas referências foram obtidas são válidos por
    // todo o bloco inseguro, e eles não sejam acessados tanto através das
    // referências ou concorrentemente através de outros ponteiros.
    unsafe {
        println!("r1 é: {}", *r1);
        *r1 = String::from("oh-oh");
        println!("r2 é: {}", *r2);
    }

    // INSEGURO. NÃO FAÇA ISSO.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 é: {}", *r3);
    */
}

Variáveis Estáticas Mutáveis

É seguro ler uma variável estática imutável:

static HELLO_WORLD: &str = "Olá, mundo!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

No entanto, como podem ocorrer corridas de dados (data races), não é seguro ler e gravar dados em variáveis estáticas mutáveis:

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // SEGURANÇA: Não há outras _threads_ que poderiam estar acessando `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // SEGURANÇA: Não há outras _threads_ que poderiam estar acessando `COUNTER`.
    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

Uniões

Unions são como enums, mas você mesmo precisa rastrear o campo ativo:

#[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 }); // Comportamento indefinido!
}

Funções Inseguras

Chamando Funções Inseguras

Uma função ou método pode ser marcado como unsafe se houver pré-condições extras que você deve respeitar para evitar comportamento indefinido:

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // SEGURANÇA: Os índices estão na ordem correta, dentro dos limites da
    // slice da string, e contido dentro da sequência UTF-8.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("contador de caracteres: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    // SEGURANÇA: `abs` não lida com ponteiros e não tem nenhum requisito de
    // segurança.
    unsafe {
        println!("Valor absoluto de -3 de acordo com C: {}", abs(-3));
    }

    // Não manter o requerimento de codificação UTF-8 viola segurança de memória!
    // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("contador caracter: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

Escrevendo Funções Inseguras

Você pode marcar suas próprias funções como inseguras (unsafe) se elas exigirem condições específicas para evitar comportamentos indefinidos.

/// Troca os valores apontadoes pelos ponteiros fornecidos.
///
/// # Segurança
///
/// Os ponteiros precisam ser válidos e corretamente alinhados.
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;

    // SEGURANÇA: ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Implementando Traits Inseguros

Assim como nas funções, você pode marcar um trait como unsafe se a implementação precisa garantir condições particulares para evitar comportamento indefinido.

Por exemplo, o crate zerocopy tem um trait inseguro que parece algo assim:

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Segurança
/// O tipo precisa ter uma representação definida e nenhum preenchimento.
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),
            )
        }
    }
}

// SEGURANÇA: `u32` possui uma representação definida e sem preenchimento.
unsafe impl AsBytes for u32 {}

Wrapper FFI seguro

Rust tem ótimo suporte para chamar funções por meio de uma interface para funções externas (Function Foreign Interface - FFI). Usaremos isso para construir um wrapper (invólucro) seguro para as funções da libc de C que você usaria para ler os nomes dos arquivos de um diretório.

Você vai querer consultar as páginas do manual:

• opendir(3)
• readdir(3)
• closedir(3)

Você também vai querer navegar pelo módulo std::ffi. Lá você encontrará um número de tipos de string que você precisará para o exercício:

Você irá converter entre todos estes tipos:

• &str para CString: você precisa alocar espaço para o caracter terminador \0,
• CString para *const i8: você precisa de um ponteiro para chamar funções em C,
• *const i8 para &CStr: você você precisa de algo que pode encontrar o caracter terminador \0,
• &CStr para &[u8]: um slice de bytes é a interface universal para "algum dado desconhecido",
• &[u8] para &OsStr: &OsStr é um passo em direção a OsString, use OsStrExt para criá-lo,
• &OsStr para OsString: você precisa clonar os dados em &OsStr para poder retorná-lo e chamar readdir novamente.

O Nomicon também tem um capítulo bastante útil sobre FFI.

Copie o código abaixo para https://play.rust-lang.org/ e implemente as funções e métodos que faltam:

// TODO: remova isto quando você terminar sua implementação.
#![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. Veja 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)>,
    }

    // Layout de acordo com a página man do Linux para readdir(3), onde ino_t e
    // off_t são resolvidos de acordo com as definições em
    // /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],
    }

    // Layout de acordo com a página man do macOS man page para 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;

        // Veja https://github.com/rust-lang/libc/issues/414 e a seção sobre
        // _DARWIN_FEATURE_64_BIT_INODE na página man do macOS para stat(2).
        //
        // "Plataformas que existiram antes destas atualizações estarem disponíveis" refere-se
        // ao macOS (ao contrário do iOS / wearOS / etc.) em Intel e 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> {
        // Chama opendir e retorna um valor Ok se funcionar,
        // ou retorna Err com uma mensagem.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Continua chamando readdir até nós obtermos um ponteiro NULL de volta.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Chama closedir se necessário.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

Solução

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. Veja 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)>,
    }

    // Layout de acordo com a página man do Linux para readdir(3), onde ino_t e
    // off_t são resolvidos de acordo com as definições em
    // /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],
    }

    // Layout de acordo com a página man do macOS man page para 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;

        // Veja https://github.com/rust-lang/libc/issues/414 e a seção sobre
        // _DARWIN_FEATURE_64_BIT_INODE na página man do macOS para stat(2).
        //
        // "Plataformas que existiram antes destas atualizações estarem disponíveis" refere-se
        // ao macOS (ao contrário do iOS / wearOS / etc.) em Intel e 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> {
        // Chama opendir e retorna um valor Ok se funcionar,
        // ou retorna Err com uma mensagem.
        let path =
            CString::new(path).map_err(|err| format!("Caminho inválido: {err}"))?;
        // SEGURANÇA: path.as_ptr() não pode ser NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("Não foi possível abrir {:?}", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Continua chamando readdir até nós obtermos um ponteiro NULL de volta.
        // SEGURANÇA: self.dir nunca é NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // Chegamos ao final do diretório.
            return None;
        }
        // SEGURANÇA: dirent não é NULL e dirent.d_name é terminado em NUL
        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) {
        // Chama closedir se necessário.
        if !self.dir.is_null() {
            // SEGURANÇA: self.dir não é NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("Não foi possível fechar {:?}", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", 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("Caracter não UTF-8 no caminho")?,
        )?;
        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"), "//! Caranguejo (Crab)\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Caracter não UTF-8 no caminho")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

Bem-vindos ao Rust para Android

O Rust é suportado para software de sistema no Android. Isso significa que você pode escrever novos serviços, bibliotecas, drivers ou até mesmo firmware em Rust (ou melhorar o código existente conforme necessário).

Hoje tentaremos chamar Rust a partir de um de seus próprios projetos. Então tente encontrar um cantinho da sua base de código onde podemos mover algumas linhas de código para o Rust. Quanto menos dependências e tipos "exóticos", melhor. Algo que analise alguns bytes brutos seria o ideal.

Configuração

Usaremos um Dispositivo Virtual Android Cuttlefish para testar nosso código. Certifique-se de ter acesso a um ou crie um novo com:

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

Consulte o Codelab para Desenvolvedor Android para maiores detalhes.

Regras de Compilação (Build Rules)

O sistema de compilação do Android (Soong) oferece suporte ao Rust por meio de vários módulos:

Veremos rust_binary e rust_library a seguir.

Binários do Rust

Vamos começar com um aplicativo simples. Na raiz de um checkout AOSP, crie os seguintes arquivos:

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

/// Imprime uma saudação na saída padrão.
fn main() {
    println!("Olá do Rust!");
}

Agora você pode compilar, enviar e executar o binário:

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

Você usa rust_library para criar uma nova biblioteca Rust para Android.

Aqui declaramos uma dependência em duas bibliotecas:

• libgreeting, que definimos abaixo,
• libtextwrap, que é um crate já oferecido em 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, // Precisamos disso para evitar erro de ligação dinâmica.
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

use greetings::greeting;
use textwrap::fill;

/// Imprime uma saudação na saída padrão.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! Greeting library.

/// Saudação `nome`.
pub fn greeting(name: &str) -> String {
    format!("Olá {nome}, prazer em conhecê-lo!")
}

Você constrói, envia e executa o binário 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

A Linguagem de Definição de Interface Android (AIDL) é compatível com Rust:

• O código Rust pode chamar servidores AIDL existentes,
• Você pode criar novos servidores AIDL em Rust.

Tutorial do Serviço de Aniversário

Para ilustrar como usar Rust com Binder, vamos passar pelo processo de criação de uma interface Binder. Em seguida, vamos implementar o serviço descrito e escrever código do cliente que fala com esse serviço.

Interfaces AIDL

Você declara a API do seu serviço usando uma interface AIDL:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    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 não está ativado por padrão
            enabled: true,
        },
    },
}

API de Serviço Gerada

Binder gera um trait correspondente à definição da interface. trait para falar com o serviço.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    String wishHappyBirthday(String name, int years);
}

Trait gerado:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Seu serviço precisará implementar este trait, e seu cliente usará este trait para falar com o serviço.

Implementação do Serviço

Agora podemos implementar o serviço AIDL:

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// A implementação de `IBirthdayService`.
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 aniversário {name}, parabéns pelos seus {years} anos!"))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

Servidor AIDL

Finalmente, podemos criar um servidor que expõe o serviço:

birthday_service/src/server.rs:

//! Birthday service.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Ponto de entrada para serviço de aniversário.
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("Falha ao registrar o serviço");
    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 erro de ligação dinâmica.
}

Implantar

Agora podemos compilar, enviar e iniciar o serviço:

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server /data/local/tmp"
adb root
adb shell /data/local/tmp/birthday_server

Em outro terminal, verifique se o serviço está sendo executado:

adb shell service check birthdayservice

Service birthdayservice: found

Você também pode chamar o serviço com 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 AIDL

Por fim, podemos criar um cliente Rust para nosso novo serviço.

birthday_server/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Chama o serviço de aniversário.
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(|_| "Falha ao conectar-se a BirthdayService")?;

    // Chama o serviço.
    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 erro de ligação dinâmica.
}

Observe que o cliente não depende de libbirthdayservice.

Compile, envie e execute o cliente em seu dispositivo:

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client /data/local/tmp"
adb shell /data/local/tmp/birthday_client Carlos 60

Happy Birthday Charlie, congratulations with the 60 years!

Alterando API

Vamos estender a API com mais funcionalidades: queremos permitir que os clientes especifiquem uma lista de frases para o cartão de aniversário:

package com.example.birthdayservice;

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

Isso resulta em uma definição de trait atualizada para IBirthdayService.

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Atualizando Cliente e Serviço

Atualize o código do cliente e do servidor para considerar a nova 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 aniversário {name}, parabéns pelos seus {years} anos!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_server/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Felis aniversárrio para vocêêêêêê"),
        String::from("E também: muito mais"),
    ],
)?;

Trabalhando com Tipos AIDL

Os tipos AIDL são traduzidos para o tipo Rust idiomático apropriado:

• Os tipos primitivos mapeiam (em sua maioria) para tipos Rust idiomáticos.
• Tipos de coleção como slices, Vecs e tipos de string são suportados.
• Referências a objetos AIDL e identificadores de arquivo podem ser enviados entre clientes e serviços.
• Identificadores de arquivo e parcelables são totalmente suportados.

Tipos Primitivos

Os tipos primitivos mapeiam (em sua maioria) de forma idiomática:

Tipos de Matriz

Os tipos de array (T[], byte[] e List<T>) são traduzidos para o tipo de array Rust apropriado, dependendo de como são usados na assinatura da função:

Enviando Objetos

Objetos AIDL podem ser enviados como um tipo AIDL concreto ou como a interface IBinder com tipo apagado:

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 {
    /** A mesma coisa, mas usando um objeto de ligação. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** A mesma coisa, mas usando `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// _Struct_ Rust implementando a interface `IBirthdayInfoProvider`.
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("Falha ao conectar-se a BirthdayService");

    // Cria um objeto de ligação para a interface `IBirthdayInfoProvider`.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Envia o objeto de ligação para o serviço.
    service.wishWithProvider(&provider)?;

    // Realiza a mesma operação, mas passando o provedor como um `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

Parcelables

Binder para Rust suporta o envio de parcelables diretamente:

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 {
    /** A mesma coisa, mas com um _parcelable_. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Falha ao conectar-se a BirthdayService");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

Enviando Arquivos

Arquivos podem ser enviados entre clientes/servidores Binder usando o tipo ParcelFileDescriptor:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** A mesma coisa, mas carrega informações de um arquivo. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Falha ao conectar-se a BirthdayService");

    // Abre um arquivo e coloca as informações de aniversário nele.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Cria um `ParcelFileDescriptor` a partir do arquivo e o envia.
    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> {
        // Converte o descritor de arquivo para um `File`. `ParcelFileDescriptor` envolve
        // um `OwnedFd`, que pode ser clonado e então usado para criar um objeto `File`.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Identificador de arquivo inválido");

        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 aniversário {name}, parabéns pelos seus {years} anos!"))
    }
}

Testes no Android

Continuando em Testes, agora veremos como os testes unitários funcionam no AOSP. Use o módulo rust_test para seus testes unitários:

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() {
//! Biblioteca de preenchimento à esquerda.

/// Preenche à esquerda `s` até `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");
    }
}
}

Agora você pode executar o teste com

atest --host libleftpad_test

A saída se parece com isso:

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

Observe como você menciona apenas a raiz da crate da biblioteca. Os testes são encontrados recursivamente em módulos aninhados.

GoogleTest

O crate GoogleTest permite assertividade de testes flexível usando matchers (correspondentes):

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

Se mudarmos o último elemento para "!", o teste falha com uma mensagem de erro estruturada apontando o erro:

---- 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 = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    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

Mocking

Para mocking, Mockall é uma biblioteca muito usada. Você precisa refatorar seu código para usar traits, que você pode então rapidamente "mockar":

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);
}

Gerando Registros (Log)

Você deve usar o crate log para logar automaticamente no logcat (no dispositivo) ou stdout (no 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:

//! Rust logging demo.

use log::{debug, error, info};

/// Registra uma saudação.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("Iniciando programa.");
    info!("As coisas estão indo bem.");
    error!("Algo deu errado!");
}

Compile, envie e execute o binário em seu 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

Os logs aparecem em 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!

Interoperabilidade

O Rust tem excelente suporte para interoperabilidade com outras linguagens. Isso significa que você pode:

• Chamar funções Rust em outras linguagens.
• Chamar funções escritas em outras linguagens no Rust.

Quando você chama funções em outra linguagem, dizemos que você está usando uma interface de função externa, também conhecida como FFI.

Interoperabilidade com C

Rust tem suporte completo para vincular arquivos de objeto com uma convenção de chamada C. Da mesma forma, você pode exportar funções Rust e chamá-las em C.

Você pode fazer isso manualmente se quiser:

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    // SEGURANÇA: `abs` não tem nenhum requisito de segurança.
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

Já vimos isso no exercício Safe FFI Wrapper .

Isso pressupõe conhecimento total da plataforma de destino. Não recomendado para produção.

Veremos opções melhores a seguir.

Usando Bindgen

A ferramenta bindgen pode gerar vínculos (bindings) automaticamente a partir de um arquivo de cabeçalho C.

Primeiro crie uma pequena biblioteca C:

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 Aniversário %s!\n", card->name);
  printf("|Parabéns pelos %i anos!\n", card->years);
  printf("+--------------\n");
}

Adicione isto ao seu arquivo Android.bp:

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

Crie um arquivo de cabeçalho wrapper para a biblioteca (não estritamente necessário neste exemplo):

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

Agora você pode gerar automaticamente as vinculações (bindings):

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

Finalmente, podemos usar as vinculações (bindings) em nosso programa Rust:

interoperability/bindgen/Android.bp:

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Bindgen demo.

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 };
    // SEGURANÇA: O ponteiro que passamos é válido porque veio de uma referência Rust,
    // e o `name` que ele contém se refere a `name` acima, que também permanece
    // válido. `print_card` não armazena nenhum dos ponteiros para usar depois
    // que ele retorna.
    unsafe {
        print_card(&card as *const card);
    }
}

Compile, envie e execute o binário em seu 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 fim, podemos executar testes gerados automaticamente para garantir que as vinculações funcionem:

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: "none", // Arquivo gerado, pule o linting
    lints: "none",
}

atest libbirthday_bindgen_test

Chamando Rust

Exportar funções e tipos do Rust para C é fácil:

interoperability/rust/libanalyze/analyze.rs

//! Rust FFI demo.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analisar os números.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) é o menor!");
    } else {
        println!("y ({y}) é provavelmente maior 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: ["."],
}

Agora podemos chamá-lo a partir de um binário C:

interoperability/rust/analisar/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"],
}

Compile, envie e execute o binário em seu dispositivo:

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers /data/local/tmp"
adb shell /data/local/tmp/analyze_numbers

Com C++

O crate CXX possibilita a interoperabilidade segura entre Rust e C++.

A abordagem geral é assim:

O Módulo Bridge

O CXX depende de uma descrição das assinaturas de função que serão expostas de cada linguagem para a outra. Você fornece essa descrição usando blocos externos em um módulo Rust anotado com a macro de atributo #[cxx::bridge].

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Estruturas compartilhadas com campos visíveis para ambas as linguagens.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Tipos e assinaturas Rust expostos ao C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // Tipos e assinaturas C++ expostos ao 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;
    }
}

Declarações de Bridge Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Tipo opaco
        fn foo(&self); // Método em `MyType`
        fn bar() -> Box<MyType>; // Função livre
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

C++ Gerado

#[cxx::bridge]
mod ffi {
    // Tipos e assinaturas Rust expostos ao C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

Resulta (aproximadamente) no seguinte 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;

Declarações de Bridge C++

#[cxx::bridge]
mod ffi {
    // Tipos e assinaturas C++ expostos ao 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;
    }
}

Resulta (aproximadamente) no seguinte 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 Compartilhados

#[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 Compartilhados

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Rust gerado:

#![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++ gerado:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

Tratamento de Erros do 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 requer profundidade > 0"));
    }

    Ok("Sucesso!".into())
}

Tratamento de Erros do 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!("Erro: {}", err);
        process::exit(1);
    }
}

Tipos Adicionais

Compilando no Android

Crie uma cc_library_static para compilar a biblioteca C++, incluindo o cabeçalho e o arquivo de origem gerados pelo 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"],
}

Compilando no Android

Crie duas regras de geração: uma para gerar o cabeçalho CXX e outra para gerar o arquivo de origem CXX. Estes são então usados como entradas para a cc_library_static.

// Gera um cabeçalho C++ contendo as vinculações C++
// para as funções exportadas do Rust em lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Gera o código C++ que o Rust chama.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

Compilando no Android

Crie um rust_binary que depende de libcxx e sua cc_library_static.

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

Interoperabilidade com Java

Java pode carregar objetos compartilhados via Java Native Interface (JNI). O crate jni permite que você crie uma biblioteca compatível.

Primeiro, criamos uma função Rust para exportar para Java:

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI demo.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// Implementação do 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!("Olá, {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"],
}

Podemos então chamar esta função do 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"],
}

Por fim, você pode criar, sincronizar e executar o binário:

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

Exercícios

Este é um exercício em grupo: Nós iremos ver um dos projetos com os quais você trabalha e tentar integrar um pouco de Rust nele. Algumas sugestões:

• Chame seu serviço AIDL com um cliente escrito em Rust.

• Mova uma função do seu projeto para o Rust e a chame.

Bem-vindos ao Rust para Chromium

O Rust é suportado para bibliotecas de terceiros no Chromium, com código original para conectar com o código C++ existente do Chromium.

Hoje, chamaremos o Rust para fazer algo simples com strings. Se você tem um pedacinho do código onde é exibida uma string UTF8 para o usuário, sinta-se à vontade para seguir esta receita em sua parte do código-fonte em vez da parte exata sobre a qual falamos.

Configuração

Certifique-se de que você pode compilar e executar o Chromium. Qualquer plataforma e conjunto de flags de compilação está OK, desde que seu código seja relativamente recente (posição de commit 1223636 em diante, correspondendo a novembro de 2023):

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(Um componente, compilação de debug é recomendado para o tempo de iteração mais rápido. Este é o padrão!)

Veja Como compilar o Chromium se você ainda não estiver nesse ponto. Atenção: configurar a compilação do Chromium leva tempo.

Também é recomendável que você tenha o Visual Studio Code instalado.

Sobre os exercícios

Esta parte do curso tem uma série de exercícios que se complementam. Faremo-os ao longo do curso em vez de apenas no final. Se você não tiver tempo para concluir uma determinada parte, não se preocupe: você pode alcançar no próximo slot.

Comparando os Ecossistemas do Chromium e do Cargo

A comunidade Rust normalmente usa cargo e bibliotecas de crates.io. O Chromium é compilado usando gn e ninja e um conjunto de dependências selecionadas.

Ao escrever código em Rust, suas escolhas são:

• Use gn e ninja com a ajuda dos templates de //build/rust/*.gni (por exemplo, rust_static_library que veremos mais adiante). Isso usa o conjunto de ferramentas e crates auditados do Chromium.
• Use cargo, mas restrinja-se ao conjunto de ferramentas e crates auditados do Chromium
• Use cargo, confiando em um conjunto de ferramentas e/ou crates baixados da internet

Daqui em diante, estaremos focando em gn e ninja, porque é assim que o código Rust pode ser compilado no navegador Chromium. Ao mesmo tempo, o Cargo é uma parte importante do ecossistema Rust e você deve mantê-lo em sua caixa de ferramentas.

Mini exercício

Dividam-se em pequenos grupos e:

• Faça um brainstorm de cenários em que o cargo pode oferecer uma vantagem e avalie o perfil de risco desses cenários.
• Discuta quais ferramentas, bibliotecas e grupos de pessoas precisam ser confiáveis ao usar gn e ninja, cargo offline, etc.

Política do Rust para Chromium

O Chromium ainda não permite que Rust seja utlizado diretamente, exceto em casos raros, conforme aprovado pelos Area Tech Leads do Chromium.

A política do Chromium sobre bibliotecas de terceiros é descrita aqui - o Rust é permitido para bibliotecas de terceiros em várias circunstâncias, incluindo se forem a melhor opção para desempenho ou para segurança.

Muito poucas bibliotecas Rust expõem diretamente uma API C/C++, o que significa que quase todas essas bibliotecas exigirão diretamente um pouco de código de integração.

O código próprio de integração Rust para um determinado crate de terceiros deve ser mantido normalmente em third_party/rust/<crate>/<version>/wrapper.

Por causa disso, o curso de hoje será fortemente focado em:

• Trabalhando com bibliotecas Rust de terceiros ("crates")
• Escrevendo código de integração para poder usar esses crates a partir do C++ do Chromium.

Se essa política mudar com o tempo, o curso evoluirá para acompanhar.

Regras de Compilação

O código Rust geralmente é compilado usando cargo. O Chromium é compilado com gn e ninja para eficiência --- suas regras estáticas permitem a máxima paralelização. O Rust não é exceção.

Adicionando código Rust ao Chromium

Em algum arquivo BUILD.gn existente do Chromium, declare um rust_static_library:

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

Você também pode adicionar deps em outros módulos Rust. Mais tarde, usaremos isso para depender de código de terceiros.

Incluindo código Rust unsafe (inseguro)

O código Rust inseguro é proibido em rust_static_library por padrão --- não será compilado. Se você precisar de código Rust inseguro, adicione allow_unsafe = true ao alvo gn. (Mais tarde no curso, veremos circunstâncias em que isso é necessário).

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
}

Dependendo de Código Rust do C++ do Chromium

Basta adicionar o alvo acima às deps de algum alvo C++ do Chromium.

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

Os tipos são omitidos no código Rust, o que torna um bom IDE ainda mais útil do que para C++. O Visual Studio Code funciona bem para Rust no Chromium. Para usá-lo,

• Verifique se o seu VSCode tem a extensão rust-analyzer, não as formas anteriores de suporte ao Rust
• gn gen out/Debug --export-rust-project (ou equivalente para seu diretório de saída)
• ln -s out/Debug/rust-project.json rust-project.json

Exercício de regras de compilação

Em sua compilação do Chromium, adicione um novo módulo Rust a //ui/base/BUILD.gn contendo:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("Olá do Rust!")
}
}

Importante: observe que no_mangle aqui é considerado um tipo de insegurança pelo compilador Rust, portanto, você precisará permitir código inseguro em seu alvo gn.

Adicione este novo módulo Rust como uma dependência de //ui/base:base. Declare esta função no topo de ui/base/resource/resource_bundle.cc (mais tarde, veremos como isso pode ser automatizado por ferramentas de geração de bindings):

extern "C" void hello_from_rust();

Chame esta função de algum lugar em ui/base/resource/resource_bundle.cc - sugerimos o topo de ResourceBundle::MaybeMangleLocalizedString. Compile e execute o Chromium e verifique se "Hello from Rust!" é impresso muitas vezes.

Se você usar o VSCode, agora configure o Rust para funcionar bem no VSCode. Isto será útil nos exercícios subsequentes. Se você tiver sucesso, poderá usar o botão direito do mouse em "Ir para definição" em println!.

Onde encontrar ajuda

• As opções disponíveis para o rust_static_library gn template
• Informações sobre #[no_mangle]
• Informações sobre extern "C"
• Informações sobre o --export-rust-project do gn
• Como instalar o rust-analyzer no VSCode

Testes

A comunidade Rust normalmente escreve testes unitários em um módulo colocado no mesmo arquivo de código sendo testado. Isso foi abordado anteriormente no curso e se parece com isso:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

No Chromium, colocamos os testes unitários em um arquivo de código separado e continuamos a seguir essa prática para o Rust --- isso torna os testes consistentemente descobríveis e ajuda a evitar a reconstrução de arquivos .rs uma segunda vez (na configuração test).

Isto resulta nas seguintes opções para testar código Rust no Chromium:

• Testes nativos Rust (ou seja, #[test]). Desencorajado fora de //third_party/rust.
• Testes gtest escritos em C++ e exercitando Rust via chamadas FFI. Suficiente quando o código Rust é apenas uma camada FFI fina e os testes unitários existentes fornecem cobertura suficiente para o recurso.
• Testes gtest escritos em Rust e usando o crate sob teste por meio de sua API pública (usando pub mod for_testing { ... } se necessário). Este é o assunto dos próximos slides.

Biblioteca rust_gtest_interop

A biblioteca [rust_gtest_interop](https://chromium.googlesource.com/chromium/src/+ /main/testing/rust_gtest_interop/README.md) fornece uma maneira de:

• Use uma função Rust como um caso de teste gtest (usando o atributo #[gtest(...)])
• Use expect_eq! e macros semelhantes (semelhantes a assert_eq! mas não falhando e não terminando o teste quando a asserção falha).

Exemplo:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Regras GN para Testes em Rust

A maneira mais simples de compilar testes gtest Rust é adicioná-los a um binário de teste existente que já contém testes escritos em C++. Por exemplo:

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

Escrever testes Rust em uma static_library separada também funciona, mas exige a declaração manual da dependência das bibliotecas de suporte: